CLI reference
The alto command starts, lists, attaches to and drives sessions, here and on your other devices. It's also
the background server and each session's process, so there's one file to install. Generated from alto 0.0.1;
each command's page has its full --help.
Sessions
| Command | What it does |
|---|---|
alto open |
Open a session in a Alto window, in a new tab if one is open, in this folder or DIR. Runs your login shell unless a program is given after `--`. (Plain `alto` starts one in the terminal it's typed in.) [aliases: term, terminal] |
alto new |
Start a session and print its id. Runs your login shell unless a program is given after `--` |
alto ls |
List running sessions, and what each is doing [alias: list] |
alto attach |
Show a session in this terminal. Ctrl-\ detaches |
alto kill |
End a session's program, or forget an ended session. --all ends every session here, asking first |
alto capture |
Print a session's screen and scrollback as plain text (an ended session's, as it last saved them). With no id, the work pane linked to this session |
Agents
| Command | What it does |
|---|---|
alto status |
This device at a glance: the service and its start at login, Tailscale and remote access, devices, sessions, keep-awake, drain and the agents found here, with the command that fixes anything wrong. Asks this device only (`alto devices` asks the others) |
alto work |
The work panes linked to this session: where an agent running in it runs its commands (`alto run -- COMMAND`), beside it where you see them, here or on another device (`--on`). With nothing after it, lists them |
alto run |
Run a command in a session's shell, where it shows, and print only its output, leaving with its exit status |
alto wait |
Wait until a session's program reaches a state, or shows some text. Exits 0 then (printing what it found), 124 after --timeout, 125 if the session ends. With no id, the work pane linked to this session |
alto send |
Type text into a session, then keys by name. With no --session, the work pane linked to this session (`alto work`) |
alto pause |
Stop agents typing into a session (`run`, `send` from an agent are refused there) until `alto resume`. You can still type. With no id, the work pane linked to this session |
alto resume |
Let agents type into a session again |
alto mcp |
Serve the session commands to an agent over MCP, on standard input and output: `claude mcp add alto -- alto mcp`. Its tools run commands in your work pane (or a session it's told to use), as `alto run` does |
Other devices
| Command | What it does |
|---|---|
alto devices |
Your other devices: those you reach (`--on NAME`), and those that reach this one. Forget, block or let one back in |
alto pair |
Pair with another person's device (your own, on the same Tailscale account, need no pairing). With nothing after it, shows a pairing string to type on the other device; with that string, pairs |
The background service
| Command | What it does |
|---|---|
alto service |
The background process that keeps sessions (started for you by any command): whether it's running and starts at login; start, stop or run it here; `install` to start it at login without the app |
alto reload |
Move the service and running sessions onto the build installed now, after an update (nothing is downloaded). Sessions move in place, their programs still running: idle ones at once, working ones once idle. Those that can't (on Windows, ones started before they could) are listed as needing a restart, which --restart does |
Look
| Command | What it does |
|---|---|
alto fonts |
Fonts Alto can download: list them, or install one |
More
| Command | What it does |
|---|---|
alto fetch |
Bring the branch of a session started with `new --repo` into this repository, as `alto/<device>-<id>`, its commits and all |
alto report |
Say what a session's program is doing (for an agent, or its hooks): idle, working, needs-you or done. A program may also say what it is (--kind) and values of its own (--set), which `describe` and `ls --json` show until it ends. With nothing to say, show it. Without --session, the session this runs in |
alto agents |
Set up agents to report their state to Alto: Claude Code, Codex. Connect agents to Alto: their hooks (Claude Code, Codex: state, and which session a conversation is in), a skill pointing them at `alto guide` (Claude Code, Codex, OpenCode, Pi), and the MCP server (Claude Code). Leave out the command to see how each agent stands |
alto describe |
What a session is and what it can be asked to do: its kind (agent, shell or job), its state, and its methods, each with what it takes and gives. With no id, the work pane linked to this session |
alto call |
Ask a session to do one thing, by a method `describe` lists, with its arguments as JSON (`--args '{"last":20}'`, or `--args -` to read them from standard input). Prints what it gives back; the arguments are checked first, so a call refused changes nothing. Exits 2 when there's no such method or the arguments are wrong, 124 when it timed out, 125 when it couldn't, and `run`'s with the command's status |
alto reply |
Reply to a message an agent was sent (12.10), from inside the session it was sent to: TEXT, or JSON with --json when the message asked for a reply of a certain shape. The sender gets it as data |
alto offer |
Offer a method of this program's to its session, served by HANDLER: each call's arguments (JSON) on its standard input, its reply (JSON) on its standard output. Runs in a session, and stays running to serve calls until the process that started it ends (or with --keep, the session does). `alto describe` lists it; `alto call` calls it |
alto answer |
Answer what a session's agent is asking (a permission prompt, a question) without its screen: `allow` or `deny`, or one of a question's options, as `describe` lists them. Refused when it's asking something else by now, so an answer never lands on another question |
alto guide |
How to use Alto, for an agent running in it: its session, reaching other sessions and machines, waiting, and the rules. The hook for Claude Code points a new conversation here |
alto events |
What happens, as it happens: sessions starting, ending, needing you and done; devices connecting, pairing, forgetting, blocking. A line each, or --json, until stopped. This device's, --on another's, or --all of them |
alto reset |
Start over: end every session here (asking first), restart the service on the build installed now, and have open windows drop their tabs for one new one. `reload` is the one that keeps programs running |
alto workspace |
Named sets of sessions, on any machines, that open whole; kept by this device. A workspace holds sessions' addresses: forgetting it, or removing one, ends nothing. With nothing after it, lists them |
alto settings |
Show this device's settings, or one, or set one: |
alto log |
What happened on this device, and who did it: sessions started and ended, who attached, typed (how much, never what) and was refused, pairings. Each entry is signed by this device and names the one before, so `alto log verify` finds any changed, removed or moved |
alto access |
Who may do what here: the rules (built in, and access.toml beside settings.toml) |
alto fleet |
Sessions on every device you reach, and how many are working, need you or are done |
alto add |
Make a machine ssh reaches one of yours: sends it the build for its OS and architecture, runs `alto install` there trusting your Tailscale login, waits for it to answer, and lists it. It needs Tailscale; without it, says how to install it and changes nothing |
alto install |
Set Alto up on this device. At a terminal with no flags, it asks each step: Tailscale, starting at login, remote access, whom to trust, and the agents found here (their hooks, Claude Code's MCP server). With flags, -y or no terminal (a server, an image, cloud-init), it asks nothing: turns remote access on, trusts what `--trust` names, starts the service at login (on Linux, running with nobody logged in), and says how others reach it. Safe to run again |
alto uninstall |
Take Alto off this device: end every session (asking first), stop the service and its start at login, take the agents' hooks out, and remove its state (devices, pairings, saved screens) and settings. The `alto` program itself stays; it says where |
Global options
Options:
--on <DEVICE>
Work with the sessions on another device, paired with before (`alto devices`), or one of your own on Tailscale by its name there: for the session commands (ls, new, attach, send, run, wait, capture, kill, pause, resume, fetch, work). A session named `studio:3`, as `ls --all` prints it, needs no --on
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
Exit statuses, for every command:
0 it worked
1 it didn't; standard error says why
2 the command line was wrong
3 `service status`: the service isn't running
124 `run`, `wait`: still going after --timeout (the command carries on)
125 `run`, `wait`: it couldn't run, or the session ended
`run` otherwise exits with its command's own status.
JSON for scripts: ls, waiting, status, work, devices and fleet take --json.