chaarDocsDownloadConsole

Reference

Terminal commands

Every chaar command and flag, every key inside the terminal screen, and how to change those keys.

This page lists everything the chaar command does. To learn how to use it, start with Use chaar in a terminal. The desktop app's keys are on Keyboard shortcuts.

Commands

CommandWhat it does
chaarOpens the session browser, a full-screen list of your machines and sessions. It needs a terminal.
chaar loginSigns you in on this device. See Sign in.
chaar logoutSigns you out on this device.
chaar listLists your workspaces, machines and sessions.
chaar connectOpens a session, or creates one. It needs a terminal.
chaar killEnds a session, without asking.
chaar serviceMakes this computer reachable from your other devices. On macOS and Linux only.

chaar, list, connect and kill sign you in themselves if needed. The service commands sign in the machine, which is separate from your sign-in. So chaar logout signs out only the command, and the machine stays reachable. To sign the machine out, use chaar service logout.

Flags for every command

FlagWhat it does
--headlessSigns in without opening a browser. chaar prints a link you can open on any device.
--sharedUses only the machines shared with you. See Machines shared with you.
-h, --helpShows help for any command, for example chaar list --help.
-V, --versionPrints the version: chaar --version.

The other flags belong to one command and are listed with it below.

chaar list

CommandWhat it prints
chaar listEvery workspace with its machines, then the machines shared with you.
chaar list workspacesYour workspaces.
chaar list machines [workspace]One workspace's machines, and whether each is online.
chaar list sessions [workspace] [machine]One machine's sessions, and how many tabs each has.

Add --json to any of these to print JSON instead: see Scripts and JSON.

chaar list on its own looks like this:

  acme
    ● studio
    ○ build-box (offline)
  Shared
    ● pi

Name a workspace or machine by its exact name, capitals included, or by the id that --json prints. In chaar list sessions the workspace comes first, so to name a machine, name its workspace too:

Terminal
$ chaar list sessions acme studio

If you leave one out and you only have one, chaar picks it. If you have several, chaar asks you to pick in the terminal.

chaar connect

CommandWhat happens
chaar connectOpens the last session you opened in chaar, or else the most recently used one.
chaar connect apiOpens the session called api, searching every workspace and the machines shared with you.
chaar connect -n apiCreates a session called api.
FlagWhat it does
-w, --workspace <workspace>Searches only that workspace's machines. You can't use it with --shared.
-m, --machine <machine>Searches only that machine.
-n, --newCreates the session instead of opening one.
--sharedSearches only the machines shared with you.

The name must match exactly, capitals included. The id that chaar list sessions --json prints works too.

  • Several sessions match: the session browser opens so you can pick one.
  • None matches, and exactly one machine is online: chaar creates the session there without asking.
  • None matches, and several machines are online: the session browser opens so you can pick a machine and press n.

chaar kill

Terminal
$ chaar kill api acme studio

It takes the session, then the workspace, then the machine. It ends the session at once, with every tab and whatever is running in it, agent chats included.

chaar kill never asks you to confirm

In a terminal, it asks only for what you left out. If the machine has one session, chaar kill with no session name ends it straight away.

Scripts and JSON

When you leave something out, chaar list machines, chaar list sessions and chaar kill ask you to pick it in a terminal. In a script, or with --json, they fail and tell you what to pass. chaar and chaar connect don't run in a script at all.

--json prints one line of JSON and never asks anything.

  • Sign in first, or the sign-in link comes out ahead of your JSON.
  • kill never confirms. Check the session with chaar list sessions first.
  • Errors go to stderr as error: …, with exit code 1. A flag or argument the command doesn't take exits with 2.

Machines shared with you

Machines someone shared with you (see Share with others) are under Shared in the session browser and in chaar list.

Add --shared to look only at those machines. They have no workspace, so the machine comes first:

Terminal
$ chaar list sessions --shared pi

chaar service

Run these on the machine itself. On Linux, the ones that change the service ask for your password. To add a machine step by step, see Install on a server.

CommandWhat it does
chaar service enableSigns the machine in if needed, then installs the chaar service and starts it.
chaar service statusSays whether the service is enabled, and whether the machine needs signing in.
chaar service logsPrints the service's log. Add -f to keep following it.
chaar service disableStops and removes the service. The machine stays signed in, and enable turns it back on.
chaar service uninstallDoes disable, then deletes the machine's sign-in and keys, its sessions list and its agent chats, without asking.
chaar service loginSigns the machine in again.
chaar service logoutSigns the machine out.
chaar service runRuns the service in this terminal.

uninstall doesn't remove the machine from your workspaces. After you update chaar, enable alone can leave the old version running: see Update.

A Mac that also has the desktop app

The app's Turn on and Quit work on this same service. Quitting the app turns it off, even if you turned it on with chaar service enable.

Keys in the session browser

The session browser ignores the mouse. The same keys work in the switcher, the same list opened from inside a session with ctrl-bs (see Keys in a session).

KeyWhat it does
j k or the up and down arrowsMove down and up.
l h or the right and left arrowsUnfold and fold.
tab, shift-tabNext and previous workspace.
g, GTop, bottom.
ctrl-d, ctrl-uHalf a page down, up.
ctrl-f or pagedown, ctrl-b or pageupA page down, up.
enterOn a session, opens it. On a tab, opens its session at that tab.
nNew session on the selected machine, with one terminal tab. It opens right away.
RRenames the session or tab.
x on a sessionAsks first, then deletes the session and ends everything running in its tabs.
x on a tabCloses the tab without asking. On the session's last tab, it asks to delete the session.
/Filters by name. esc clears the filter.
rReloads the list.
?Lists every key.
qQuits. In the switcher, goes back to your session.

Keys in a session

Every key goes to the program in the tab, except the prefix ctrl-b. Press it, let go, then press one of these:

KeyWhat it does
ctrl-bdLeaves. The session keeps running.
ctrl-bsOpens the switcher. Pick a session and press enter.
ctrl-bn, ctrl-bpNext and previous session.
ctrl-bcNew session on this machine.
ctrl-b1 to ctrl-b9Goes to a session by its number.
ctrl-biOpens Needs you: everything waiting on you across all your machines, most urgent first. enter opens that tab.
ctrl-b?Lists every session key.
ctrl-bctrl-bSends ctrl-b to the program.

Agent chats, and programs that report their status, get a mark on their frame and on their row in the session browser. Here the marks are text, such as ? for Needs your answer: see Get notified. To give your own scripts a mark, see Show status from your scripts. While chaar is running, it also asks your terminal to show a notification when something needs you, fails or finishes off screen. Whether one appears depends on your terminal.

Tabs and splits

Splits, closes, resizes and moves you make here are saved with the session, so your other devices get them too. New tabs are always terminal tabs.

KeyWhat it does
ctrl-b%Splits the tab: a new terminal to its right.
ctrl-b"Splits the tab: a new terminal below it.
ctrl-bxCloses the tab without asking, and ends what's running in it. On the session's last tab, it asks to delete the session. On an agent chat's tab, it ends the agent.
ctrl-bzFull screen on or off. Only your terminal shows it full screen. Other devices keep the layout.
ctrl-boNext tab.
ctrl-b then h j k l or an arrowMoves to the tab that way.
ctrl-b then H J K LMoves the nearest divider.
ctrl-bmMove mode: swap the tab with a neighbour using h j k l, and finish with enter.

In a session, the mouse can also move between tabs, resize them and copy text.

Scroll, find, copy and paste

ctrl-b[ or the mouse wheel starts scrolling. ctrl-b/ starts scrolling with find.

KeyWhat it does
pageup, pagedownA page up, a page down.
g, GTop, bottom.
v, then move, then ySelects text, then copies it.
/, then type and press enterFinds text. n and N go to the older and newer match.
esc or qStops scrolling.

To copy, chaar asks your terminal to set the clipboard, so copying works only if your terminal allows it. Your terminal's own paste goes to the tab you're typing in.

Change the keys

You change the keys inside chaar with a file. The desktop app's shortcuts are separate: see Settings.

  1. Make the file

    Create ~/.config/chaar/keys.toml. It's in ~/.config on macOS too. On Windows, it's .config\chaar\keys.toml in your user folder.

  2. Add your keys

    Each line is a key and the action it does. This example changes the prefix to ctrl-a, swaps % for | to split right, and adds two more keys:

    toml
    prefix = "ctrl-a"
    
    [after-prefix]
    "|" = "split-right"
    "%" = "none"
    
    [root]
    "alt-h" = "focus-left"
    
    [browser]
    "d" = "delete-session"
  3. Start chaar again

    chaar reads the file only when it starts. Quit it and run it again. chaar skips a wrong line and shows a warning.

The settings

SettingWhat it holds
prefixThe prefix key for sessions. The default is ctrl-b.
[after-prefix]Keys you press after the prefix in a session.
[root]Keys that work in a session without the prefix. The program in the tab no longer gets these keys.
[browser]Keys in the session browser, and in the switcher that ctrl-bs opens.
  • A new line adds a key. The action's default keys keep working.
  • "none" removes a key, as in "%" = "none".
  • A key is one character as you type it (x, G), or a named key such as enter, esc, tab, space, up or f1. Put ctrl-, alt- or shift- in front to hold that key too. A terminal can't send cmd-.

Action names

UnderActions
[browser]down, up, top, bottom, half-page-down, half-page-up, page-down, page-up, fold, unfold, next-workspace, prev-workspace, open, back, new-session, filter, reload, rename-session, delete-session, quit, shortcuts
[after-prefix] or [root]split-right, split-down, close-tab, full-screen, next-tab, focus-left, focus-down, focus-up, focus-right, resize-left, resize-down, resize-up, resize-right, move, next-session, prev-session, session-1 to session-9, new-session, search (switch session), needs-you, scroll, term-find, detach, shortcuts

Each action's default key is in the key tables above. back is esc in the session browser, search is ctrl-bs, term-find is ctrl-b/, and session-1 to session-9 are ctrl-b1 to ctrl-b9.

Files and environment

Files

WhatmacOSLinux
Your sign-in for the command, and what it remembers~/Library/Application Support/chaar/cli/~/.local/share/chaar/cli/
The machine's sign-in, keys, sessions list and log~/Library/Application Support/chaar/chaard/~/.local/share/chaar/chaard/
Your keys file~/.config/chaar/keys.toml~/.config/chaar/keys.toml

On Windows, the command's folder is %APPDATA%\chaar\cli\, and the keys file is .config\chaar\keys.toml in your user folder.

Environment

CHAAR_CONNECT_TIMEOUT_SECS sets how long chaar waits for a machine before giving up, in seconds. The default is 15 seconds.

Terminal
$ CHAAR_CONNECT_TIMEOUT_SECS=30 chaar connect

Stuck? Ask in the Discord community.

↑↓Move↩Open