Scripts

This page shows how to load your Lua scripts from the command line, to find a mistake in init.lua before you open tt.

Run it

tcli scripts

The command loads init.lua from the scripts folder of the root (~/.config/tilde/scripts by default) and every file it requires, the way Tilde does at start. It prints what the scripts print and log.* as they run, one line each: a print line starts with Lua:, and warning or error is in front of the lines that are not plain information. Then it lists the commands and the rules that the scripts added.

Lua: loaded
Scripts folder: /home/ada/.config/tilde/scripts
Commands added by the scripts: 1
  hello - Says hello.
Rules added by the scripts: 2
  newsletter (mail)
  my-mentions (chat)

The first run on a new machine writes the default init.lua and keybind.lua if the folder has none, as Tilde does at start, and says so (Wrote the default script ...).

Read an error

A script that stops with an error gives a warning line with the file, the line and the message, then the usual report, and the last line counts the errors:

warning Lua error in init.lua: Lua-CSharp: [string "init.lua"]:19: 'rules.mail'
failed: rule 'bad': unknown condition 'form'; valid conditions: from, to,
subject, header, account, folder
Scripts folder: /home/ada/.config/tilde/scripts
Commands added by the scripts: 0
Rules added by the scripts: 0
1 script error(s): see the lines above.

A mistake in a rule (rules.mail, rules.chat) or in a key (keys.bind) shows up here: an unknown key name, a digit as the first key of a binding, a command name with a space. The lines of the script after the error do not run.

What it does not do

It starts no service, so no account is connected. No mail or chat event reaches a handler, and jobs and timers do not run. What runs is the code at the top of the scripts and the startup handlers. That is enough to see a syntax error, a wrong rule or a failing require before Tilde runs them for real.

A call that needs an account, such as rules.run('work', 'INBOX') at the top of a script, fails here because no account is connected. The command then exits with 1 for a script that works in Tilde. A log.error in a script is written as error ... but is not a failure: only a script that stops with an error is.

Exit codes

• 0: the scripts loaded.
• 1: a script failed, or the engine is off (enabled = false in [scripting]).
• 2: an argument was given. The command takes none.

To apply the rules to real mail use tcli rules. The functions that a script can call are in the Lua API, and the first script is on Scripts.