Reference

The supported torio command surface and the fixed boundaries of Torio.

Running the binary

Build with go build -o torio ./cmd/torio, then put the result on your PATH — for example sudo install -m 755 torio /usr/local/bin/torio. Every command below is written as torio … and assumes that.

A freshly built binary sits in the repository root and is not on your PATH, and your shell does not search the current directory, so torio yields command not found until you install it. Running it in place as ./torio … from the repository root also works, but then every command needs the prefix.

Command surface — torio vm

Controls the torio Lima VM. torio vm init creates it; every other subcommand operates on the existing instance. The parent takes no action itself; an absent or unknown subcommand is a usage error.

Command surface — torio serve

Manages the loopback-only Hermes Desktop backend as a user systemd service. It accepts no secrets.

Command surface — torio brain

Manages the private Second Brain: a Markdown vault at /home/hermes/brain, versioned by a local Git repository, owned by hermes, and registered with Hermes as its own project so any session can search it. The parent takes no action itself; an absent or unknown subcommand is a usage error.

Output never contains note names or note content — not in success output, not in error.details. Every command reports bounded aggregate metadata only: file counts, total bytes, a manifest digest, and stable drift markers. This is the Brain's privacy boundary, not a matter of brevity.

import refuses or skips credential-shaped files, repository metadata, links, hardlinks, special files, and executables. Existing data is never overwritten — the single exception is an untouched scaffold that Torio itself created.

Sessions that were already open when init ran will not see the retrieval skill: Hermes caches a skill's prompt per backend process, so restart them.

Getting the Brain back out

Torio brings data in and does not take it out. There is no torio brain export. Copying the Brain to your host is an explicit thing you do:

limactl copy torio:/home/hermes/brain/ <host-destination>/

That is your command, not a Torio feature: nothing verifies the result, and Torio does not call it a backup.

Command surface — torio project

Attaches repositories to the guest, inspects them, and forgets them. The parent takes no action itself; an absent or unknown subcommand is a usage error.

The workspace path is not an input. It is always derived as /home/hermes/projects/<id> — never taken from you, never stored in config. Without --id, the id is <name> itself, which must be a lowercase slug.

Torio stores no Git credentials. A remote the guest cannot already read without prompting fails closed; the fix is a human granting access on the guest, outside Torio, not a retry.

add resets, cleans, and deletes nothing on the guest, so a rerun after a failure finishes the work rather than starting over.

Routine terminals and push capability are separate

Use torio project enter <id> for ordinary editing, checks, and local commits. The SSH transport disables agent forwarding and connection multiplexing, so it cannot reuse a push-capable operator connection.

The persistent Hermes backend has read access and nothing more. project shell forwards your SSH agent for exactly as long as the session lasts, and the capability leaves with you when you exit.

The session is preflighted first — the project registered, the VM bootstrap-verified, the checkout present with the registered origin and shared permissions, your local agent holding an identity to forward. Torio never test-pushes to prove any of it, and once you exit it makes no claim about what you pushed. Check the remote yourself.

The session is not bounded by --timeout; you end it.

Command surface — torio mcp

Prepares and verifies the guest boundary that a future MCP broker will use. The parent command takes no action itself; an absent or unknown subcommand is a usage error.

install accepts no secrets. It may report changed:true together with an error when a durable mutation succeeded before a later verification failed. That partial state is retained in JSON details and the human error explains the required rerun or backend restart.

Both subcommands report the grant they verified: every service in /etc/torio-mcp/policy.d/, its upstream endpoint, how many tools it allows and how many of those write. Nothing about a service is built into the CLI — a service is a policy document, and adding one means writing a second file as root. Under --json the grant is a policy object with a services array ordered by name, alongside the generation digest a running broker publishes, so a report and the process enforcing policy can be compared rather than assumed equal.

A reported write tool is a count, not a capability. The count exists because a document that marks writes must be able to say how many it grants; no released binary sends MCP traffic upstream.

This is custody preparation, not an active integration. The released CLI does not package, install, or activate the dormant broker and relay binaries. It does not perform OAuth or send MCP traffic upstream. Runtime transport and credential lifecycle remain blocked by ADR-0004 until a complete contract is accepted.

Command surface — torio version

This is the only place Torio names its own version. Nothing else in the CLI or in these docs is labelled by release, because the label would not tell you anything you could act on — and it would be wrong the moment the next one shipped.

A binary built straight from a checkout reports dev with an unknown commit; that is expected, not a fault.

Readiness and exit semantics

• torio vm bootstrap fails closed on any drift or unverifiable state with exit 6 and remediation. A rerun is success only when every postcondition is proven.
• torio serve start and restart fail closed unless the systemd state is active and GET /api/status answers 200 through loopback.
• torio serve status exits non-zero when not ready: 3 = not installed or inactive; 6 = active but the endpoint is dead.
• torio with no subcommand is a usage error (exit 2); a missing limactl is exit 8; an unmet precondition such as a stopped VM is exit 3.

Global flags

Four flags are accepted by every command, before or after the subcommand. This is the whole list; an unknown flag is a usage error (exit 2), never silently ignored, and there is no global --force.

Fixed boundaries

Rootful Docker for the hermes guest identity is forbidden. Bootstrap verifies hermes is not in the docker group.

Deployment

This site is served at torio.dev by Vercel, straight from the committed site/ output: a minimal vercel.json declares the output directory, and there is no build step, no framework, and no runtime dependency. Account, project, and DNS configuration live outside the repository, with the operator.

The pages under site/ are generated by scripts/build_docs.py from the Markdown sources in docs/content/. The generated files are committed, so a push to main is a deploy.