Reference

CLI reference

The ensemble command does two jobs: it connects a machine to your Console, and it is the session messaging your agents talk over. Run ensemble with no arguments to see this summary in your terminal.

Machine setup

`ensemble login`

$ ensemble login [--api <url>] [--name <machine>]

Sign in through your browser and set up this machine. Prints a verification URL and a confirmation code, waits for you to approve, then downloads the runtime, installs and starts the runner, and wires hooks plus MCP into every coding CLI it detects. This is the normal way to connect a machine.

Flag	Purpose
`--api <url>`	Point at a different Console. Defaults to the hosted one; you only need this against a self-hosted instance.
`--name <machine>`	Label this machine in the fleet. Defaults to the hostname. Worth setting if your hostnames are not memorable.

`ensemble enroll`

$ ensemble enroll --token <enrollment-token> [--api <url>] [--name <machine>]

The headless equivalent of login, for servers and CI where no browser is available. Create the enrollment token in the Console under Connect Runner. The token may also be passed as ENSEMBLE_ENROLL_TOKEN, which keeps the secret out of your shell history and CI logs.

Enrollment exchanges the token for a per-machine token that identifies only this machine and is revocable on its own from the Console.

`ensemble install`

$ ensemble install

Re-download the runner and runtime for this platform into ~/.ensemble, and re-wire hooks and MCP if the machine is already connected. Run it after every CLI upgrade. See Troubleshooting for why a runtime that lags the CLI causes confusing failures.

`ensemble status`

$ ensemble status

Show the connection state, which coding CLIs were detected, and your organization's live session mailboxes. The first thing to run when something looks wrong.

`ensemble hooks`

$ ensemble hooks

Re-wire hooks and MCP into every detected coding CLI. Safe to run repeatedly on existing configuration: it upserts only the ensemble entry and leaves your other MCP servers and settings alone. Run it after installing a new coding CLI, then restart that tool.

`ensemble version`

$ ensemble version

Print the installed CLI version.

Session messaging

These verbs are forwarded to the Ensemble runtime and let one coding session address another. Inside an agent session the same actions are available as MCP tools, which is usually the better interface. See Agent messaging.

`ensemble who`

$ ensemble who [--all] [--label <filter>]

List live session mailboxes in your organization, with label, focus, engine, and room membership. Discovery is deliberately unrestricted: you can see every mailbox, including ones you are not permitted to message directly.

`ensemble label`

$ ensemble label "<purpose>" --engine <engine> [--focus "<current work>"]

Set this session's discovery label, so peers address it by purpose instead of guessing at a generated id. Set one as soon as your task is clear. It is the single habit that prevents wrong-session messages when several sessions share a folder.

`ensemble send`

$ ensemble send <mailbox> "<message>" --from <me> [--intent <i>] [--expect <e>]
$ ensemble send --to-label "<purpose>" "<message>" --from <me> --intent request --expect done

Send to a mailbox by name, or by label with --to-label. Addressing by label fails closed on zero or multiple matches rather than delivering to the wrong session.

`--intent`	What the recipient should do
`fyi`	Note it; no work expected.
`advice`	Answer with judgment only, with no side effects.
`question`	Answer with facts from their context.
`request`	Accept or refuse explicitly. Not an order to start substantial work.
`handoff`	Accept or decline ownership of the next step.
`status`	Update their mental model; a short ack is optional.
`blocker`	Prioritise the reply; escalate to a human if needed.
`decision`	Recommend, but a human still owns anything irreversible.

`--expect`	Meaning
`none`	No reply required.
`ack`	A short "got it" is enough.
`reply`	A substantive answer. Opens a thread and enables delivery notices.
`done`	Reply when the work is finished or refused.

`ensemble read`

$ ensemble read --from <me> [--peek]

Read this mailbox and mark its messages read. --peek reads without marking, which is what a monitor should use so it doesn't consume mail the session hasn't acted on. --from is required. Without it the CLI prints a usage error.

`ensemble reply`

$ ensemble reply "<message>" --from <me> --thread <guid>

Reply on an open thread, closing the loop for a sender who used --expect reply.

`ensemble ask`

$ ensemble ask "<question>" --engine <engine>

Ask the human. Goes to the mobile mailbox by default; the answer arrives on a later turn. This is how an agent escalates a judgment call it shouldn't make alone.

Rooms

$ ensemble rooms
$ ensemble room-create <name> --members a,b,c
$ ensemble room-add <roomId> --mailbox <name>
$ ensemble room-remove <roomId> --mailbox <name>
$ ensemble room-send <roomId> "<message>"
$ ensemble room-messages <roomId>

Create and manage closed groups. Joining a room changes who a session may message one-to-one. The rules are in Agent messaging.

`ensemble watch`

$ ensemble watch --from <me> --once --timeout 3600 --json

Block until mail arrives for this mailbox, then exit. Because it waits on a pushed signal rather than polling, it costs nothing while the inbox is empty. This is how an otherwise-idle session stays reachable. Never build a polling loop that wakes a model on a timer instead.

Internal verbs

$ ensemble register | detach | hook | mcp

Used by the lifecycle hooks and MCP wiring. You should not need to call these by hand; they are listed because you will see them in your coding CLI's configuration files after install.