chaarDocsDownloadConsole

Reference

Show status from your scripts

Copy-paste lines that put a status mark on a terminal tab, list it in Needs you and notify you.

Make a script in a terminal tab show Working, Done, Needs your OK or Failed, as agent chats do, by printing one line.

When the script needs you, fails or finishes, chaar lists it in Needs you and notifies you. Agent chats report their status on their own. An agent you start yourself in a terminal tab shows marks only if it prints these lines: see Work with AI agents.

Try it

Run this in a terminal tab, then switch to another tab within 10 seconds:

Terminal
$ printf '\033]7501;state=working\a'; sleep 10; printf '\033]7501;state=done\a'

The tab shows Working, then Done, and you get a notification.

In a script, report as you go:

Terminal
printf '\033]7501;state=working\a'
if make test; then
  printf '\033]7501;state=done\a'
else
  printf '\033]7501;state=error\a'
fi

The machine reads these lines, not your device, so the status keeps updating while no app is open.

The line for each status

Copy the line for the status you want.

Working

Terminal
$ printf '\033]7501;state=working\a'

Working, 40%

Terminal
$ printf '\033]7501;state=working:progress=40\a'

Needs your OK

Terminal
$ printf '\033]7501;state=blocked:kind=permission\a'

Needs your answer

Terminal
$ printf '\033]7501;state=blocked:kind=question\a'

Needs your sign-in

Terminal
$ printf '\033]7501;state=blocked:kind=auth\a'

Needs you, without saying what for (◆ in the chaar command)

Terminal
$ printf '\033]7501;state=blocked\a'

Done

Terminal
$ printf '\033]7501;state=done\a'

Failed

Terminal
$ printf '\033]7501;state=error\a'

No mark, at rest

Terminal
$ printf '\033]7501;state=idle\a'

Needs you, Done and Failed notify you, unless you're looking at the tab. Done and Failed stay until someone looks at the tab. What each mark means is on Get notified.

How a line is built

Each line starts with \033]7501;, then key=value pairs separated by :, and ends with \a. In printf, \033 is the Escape character and \a is the bell character:

\033]7501;state=blocked:kind=question\a
  • Print it to standard output or standard error. When your output goes to a file or a pipe, print it to the terminal itself: printf '\033]7501;state=working\a' > /dev/tty.
  • Send every key you want shown on every line. A later line replaces the earlier one for the same job (see Report more than one job).
  • The whole line can be at most 4096 bytes.
KeyWhat it is
stateRequired. idle, working, done, blocked, error or clear. idle says the program is at rest and shows no mark. clear removes the status.
kindWith blocked: permission for an OK, question for an answer, auth for a sign-in or token.
progressWith working: a whole number from 0 to 100.
msgOne line for people: what it's doing, waiting for or finished. In base64, at most 2048 bytes of text.
titleA short label for people, in base64. Desktop notifications can name the tab with it.
appYour program's name, such as deploy. Used as the name when there's no title.
idA name for this job, when you report more than one.

Add a message

To say what your script is waiting for, put it in msg, in base64:

Terminal
$ printf '\033]7501;state=blocked:kind=permission:msg=%s\a' "$(printf %s 'Deploy to production?' | base64)"

The message shows in Needs you, as in Needs your OK · build-box · Deploy to production?, in desktop tooltips, and in desktop and chaar command notifications. Phone notifications never include it.

Everyone who can see the machine sees your status

Statuses and messages go to everyone who can see this machine in chaar, not only to you. Keep passwords, tokens and other secrets out of msg and title. See Who can reach your machine.

Report more than one job

To report several jobs at once, such as a build and its tests, give each one a name with id:

Terminal
$ printf '\033]7501;id=build:state=working\a'
Terminal
$ printf '\033]7501;id=test:state=blocked:kind=question\a'

The tab shows its most urgent job, here Needs your answer. A line without id is the tab's main status. A / in an id puts one job beneath another: test/unit sits beneath test.

Clear a status

Terminal
$ printf '\033]7501;state=clear\a'

With no id, this clears every status in the tab. With an id, it clears that job and the ones beneath it, so id=test also clears test/unit.

chaar also clears some for you:

  • At a new prompt, chaar clears Working and needs-you statuses. Done and Failed stay. This needs a shell that marks its prompts with the OSC 133 prompt mark, which most shell integrations send. A tool that stops without clearing doesn't stay Working, and a line like this you type at the prompt lasts only until the next prompt, so run it from a script.
  • On a full reset, printf '\033c' clears every status, and the screen too.

Show progress the common way

chaar also reads the progress line that many other terminals understand:

Line to printchaar shows
printf '\033]9;4;1;40\a' Working, 40%
printf '\033]9;4;3\a' Working
printf '\033]9;4;2\a' Failed
printf '\033]9;4;0\a'No mark

Don't mix the two kinds of line in one tab. Once a tab gets one of the status lines above, chaar ignores these there until a full reset.

Set the tab's title on the phone

The standard window title line gives the tab a title:

Terminal
$ printf '\033]2;%s\a' 'Deploying'

\033]0; in place of \033]2; works too.

On the phone, a tab nobody renamed shows this title. The desktop app and the chaar command keep the name you gave the tab, or else the name of the program running in it.

Check that the terminal reads these lines

From a program that reads its input, print:

\033]7501;?\a

chaar writes the same \033]7501;?\a back to the tab's input, so your program reads it like typed keys.

If a status doesn't show

  • A line with a mistake, such as a missing state or a msg that isn't valid base64, is dropped with no error.
  • The machine reads statuses about once a second while an app watches it, so a state that lasts less than that may never show.

Stuck? Ask in the Discord community.

↑↓Move↩Open