Watch

This page shows how to get one line on the standard output for every event of your accounts: a new message, a chat message, a mention, a rule that fired and a change of connection. A script can read those lines.

Start it

tcli watch

The command starts the accounts as Tilde does (IMAP IDLE, the Maildir watcher, the chat clients) and writes one line for each event until you press Ctrl-c. By default it shows:

• a mail that arrives (MailMessageReceived);
• a chat message and a mention (ChatMessageReceived, ChatMention);
• a rule that fired on a message that arrived (RuleApplied);
• an account that is unavailable and a change of connection (ConnectionStateChanged).

The listening starts before the accounts do, so an account that cannot connect shows up as a ConnectionStateChanged line. The history that a chat server sends when you join a room is not shown by default.

Read a line

A line has four columns separated by tabs: the time (ISO 8601 with the offset), the kind of the event, the account (- when the event belongs to none) and then the details as name=value. This is a mail that arrived and the rule that sorted it:

2026-11-07T11:19:44+01:00  MailMessageReceived  work  folder=INBOX  id=1793894999.3_1.host  from=News <news@example.com>  subject=Second digest
2026-11-07T11:19:45+01:00  RuleApplied  work  ruleKind=Mail  location=INBOX  messageId=1793894999.3_1.host  subject=Second digest  rules=newsletter  done=3  failed=0

• A mail has folder, id, from and subject. A chat message has channel, sender and text.
• RuleApplied has ruleKind (Mail or Chat), location (the folder, or the id of the channel), messageId, subject (a mail only), rules (the names, separated by commas), and the number of steps done and failed. It appears after the message line, when at least one rule matched. tcli rules does not write it.
• A tab, a line break or an escape inside a value is written as a space, so every event is one line and a text cannot give an order to your terminal.

Pick what you see

tcli watch --account work
tcli watch --all
tcli watch --json

• --account shows only the events of one account. An account that does not exist exits with 2.
• --all shows every event of the event bus, typing notices and flag changes included, and the history of a room (with history=true).
• --json writes one JSON object for each line, with time, kind, account (null when there is none) and one property for each detail. The text is kept as it is, and rules is a list. A detail that is called kind, time or account is named detailKind, detailTime or detailAccount.

Use it in a script

The standard output holds only the lines, and the header is not printed, so the output can be piped:

tcli watch | while IFS=$'\t' read -r time kind account details; do
    [ "$kind" = MailMessageReceived ] && notify-send "$account" "$details"
done

tcli watch | head -n 1 waits for the first event and ends by itself: when the reader is gone the command stops. A problem with the command itself (an account that does not exist, a configuration that cannot be read) goes to the standard error, and the log goes to the log file.

Stop it

Ctrl-c ends it with exit code 0 once the accounts are closed. It waits up to 30 seconds for that; the other commands wait 5. Ctrl-c while the accounts are still starting gives 130. Exit code 2 is an account that does not exist, and 1 is Tilde not starting.

It is Tilde, running

Because the command starts the services, your rules, scripts and jobs run while it watches, on the mail that arrives too, and so does the cache. Close tt first if it works on the same accounts. The rules are on Rules for mail and Rules for chat, and every option is in the reference of tcli.