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
| Command | What it does |
|---|---|
chaar | Opens the session browser, a full-screen list of your machines and sessions. It needs a terminal. |
chaar login | Signs you in on this device. See Sign in. |
chaar logout | Signs you out on this device. |
chaar list | Lists your workspaces, machines and sessions. |
chaar connect | Opens a session, or creates one. It needs a terminal. |
chaar kill | Ends a session, without asking. |
chaar service | Makes 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
| Flag | What it does |
|---|---|
--headless | Signs in without opening a browser. chaar prints a link you can open on any device. |
--shared | Uses only the machines shared with you. See Machines shared with you. |
-h, --help | Shows help for any command, for example chaar list --help. |
-V, --version | Prints the version: chaar --version. |
The other flags belong to one command and are listed with it below.
chaar list
| Command | What it prints |
|---|---|
chaar list | Every workspace with its machines, then the machines shared with you. |
chaar list workspaces | Your 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
● piName 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:
$ chaar list sessions acme studioIf 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
| Command | What happens |
|---|---|
chaar connect | Opens the last session you opened in chaar, or else the most recently used one. |
chaar connect api | Opens the session called api, searching every workspace and the machines shared with you. |
chaar connect -n api | Creates a session called api. |
| Flag | What 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, --new | Creates the session instead of opening one. |
--shared | Searches 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
$ chaar kill api acme studioIt 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.
killnever confirms. Check the session withchaar list sessionsfirst.- Errors go to stderr as
error: …, with exit code1. A flag or argument the command doesn't take exits with2.
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:
$ chaar list sessions --shared pichaar 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.
| Command | What it does |
|---|---|
chaar service enable | Signs the machine in if needed, then installs the chaar service and starts it. |
chaar service status | Says whether the service is enabled, and whether the machine needs signing in. |
chaar service logs | Prints the service's log. Add -f to keep following it. |
chaar service disable | Stops and removes the service. The machine stays signed in, and enable turns it back on. |
chaar service uninstall | Does disable, then deletes the machine's sign-in and keys, its sessions list and its agent chats, without asking. |
chaar service login | Signs the machine in again. |
chaar service logout | Signs the machine out. |
chaar service run | Runs 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).
| Key | What it does |
|---|---|
| j k or the up and down arrows | Move down and up. |
| l h or the right and left arrows | Unfold and fold. |
| tab, shift-tab | Next and previous workspace. |
| g, G | Top, bottom. |
| ctrl-d, ctrl-u | Half a page down, up. |
| ctrl-f or pagedown, ctrl-b or pageup | A page down, up. |
| enter | On a session, opens it. On a tab, opens its session at that tab. |
| n | New session on the selected machine, with one terminal tab. It opens right away. |
| R | Renames the session or tab. |
| x on a session | Asks first, then deletes the session and ends everything running in its tabs. |
| x on a tab | Closes the tab without asking. On the session's last tab, it asks to delete the session. |
| / | Filters by name. esc clears the filter. |
| r | Reloads the list. |
| ? | Lists every key. |
| q | Quits. 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:
| Key | What it does |
|---|---|
| ctrl-bd | Leaves. The session keeps running. |
| ctrl-bs | Opens the switcher. Pick a session and press enter. |
| ctrl-bn, ctrl-bp | Next and previous session. |
| ctrl-bc | New session on this machine. |
| ctrl-b1 to ctrl-b9 | Goes to a session by its number. |
| ctrl-bi | Opens 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-b | Sends 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.
| Key | What it does |
|---|---|
| ctrl-b% | Splits the tab: a new terminal to its right. |
| ctrl-b" | Splits the tab: a new terminal below it. |
| ctrl-bx | Closes 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-bz | Full screen on or off. Only your terminal shows it full screen. Other devices keep the layout. |
| ctrl-bo | Next tab. |
| ctrl-b then h j k l or an arrow | Moves to the tab that way. |
| ctrl-b then H J K L | Moves the nearest divider. |
| ctrl-bm | Move 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.
| Key | What it does |
|---|---|
| pageup, pagedown | A page up, a page down. |
| g, G | Top, bottom. |
| v, then move, then y | Selects text, then copies it. |
| /, then type and press enter | Finds text. n and N go to the older and newer match. |
| esc or q | Stops 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.
Make the file
Create
~/.config/. It's inchaar/ keys .toml ~/.configon macOS too. On Windows, it's.config\chaar\keysin your user folder..toml 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"Start chaar again
chaarreads the file only when it starts. Quit it and run it again. chaar skips a wrong line and shows a warning.
The settings
| Setting | What it holds |
|---|---|
prefix | The 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 asenter,esc,tab,space,uporf1. Putctrl-,alt-orshift-in front to hold that key too. A terminal can't sendcmd-.
Action names
| Under | Actions |
|---|---|
[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
| What | macOS | Linux |
|---|---|---|
| Your sign-in for the command, and what it remembers | ~/Library/ | ~/.local/ |
| The machine's sign-in, keys, sessions list and log | ~/Library/ | ~/.local/ |
| Your keys file | ~/.config/ | ~/.config/ |
On Windows, the command's folder is %APPDATA%\chaar\cli\, and the keys file is .config\chaar\keys in your user folder.
Environment
CHAAR_ sets how long chaar waits for a machine before giving up, in seconds. The default is 15 seconds.
$ CHAAR_CONNECT_TIMEOUT_SECS=30 chaar connectStuck? Ask in the Discord community.