Commands

commands.add makes a command that you can type after : in tt, bind to a key or run from another script. This page adds one, runs it, and then lists the rules a command follows.

Add a command

Put this in ~/.config/tilde/scripts/init.lua:

commands.add("hello", function(args)
  return "Hello, " .. (args[1] or "world")
end, "Says hello.")

Load the script and look at the commands in the output:

tcli scripts

Commands added by the scripts: 1
  hello - Says hello.

In tt, type :hello Ada and press Enter. The bottom bar shows Hello, Ada.

The rules of a command

• The name has 1 to 64 characters: lowercase letters, digits, _, - and .. It starts with a letter and has no empty part between dots, so hello.twice is valid and hello..twice is not.
• The function gets one table of strings, one for each word typed after the name. Double quotes group words: :hello "Ada Lovelace" gives args[1] = "Ada Lovelace". There is no escape, so a word cannot hold a double quote. A count typed before a key that is bound to the command is the first word (see Keys from Lua).
• If the function returns a string, that string is the message of the command. Any other value is ignored. A message is cut at 300 characters, and control characters become spaces.
• The description is optional and is cut at 120 characters.
• Adding a name again replaces your own command. A native command cannot be replaced, and the names that start with keys.fn. are kept for functions bound to keys.
• A command that fails when you run it from tt or a key shows name: <error> as its message, and the error is reported as a script_error with the source command name (see Events).
• A reload of the scripts forgets every command that scripts added.

Remove, list and run

commands.add("hello", function(args)
  return "Hello, " .. (args[1] or "world")
end, "Says hello.")

commands.add("hello.twice", function(args)
  local first = commands.run("hello", args[1] or "world")
  local second = commands.run("hello", "again")
  return first.message .. " / " .. second.message
end, "Runs hello two times.")

local result = commands.run("hello.twice", "Ada")
print(result.ok, result.message)

commands.remove("hello")
print(commands.run("hello").message)

for _, name in ipairs(commands.list()) do
  print(name)
end

tcli scripts prints true Hello, Ada / Hello, again, then Unknown command 'hello'., and the names of the commands.

• commands.run(name, ...) runs any command, native or script, with the words you give and waits for it. It returns a table: ok is true when the command ran, and message is what it returned or why it failed.
• commands.list() returns the names of all commands in the order they were added: the ones of Tilde and the ones of your scripts. The commands of tt are in the reference of tt commands.
• commands.remove(name) removes a command your scripts added. An unknown name, or a native command, is ignored.
• A command that a script runs with commands.run runs in the same unit of work as the script, so it shares its limit on instructions. A script cannot run scripting.reload: it fails with scripting.reload: The scripts cannot be reloaded from a script.

All the functions are in the Lua API reference. A C# plugin adds native commands: see Commands, Lua modules and events.