CLI Reference
Every actor subcommand, its arguments, and a minimal example.
The complete actor command surface. Run actor --help or
actor <cmd> --help for the in-terminal version. Subcommands other than
claude are thin front-ends over the same operations the main session's
MCP tools call.
actor claude
Open the interactive main session against the local daemon.
actor claude [ARGS...]
ARGS are forwarded verbatim to the claude binary. This is the only
interactive entry point.
actor list
List sessions and their status.
| Flag | Meaning |
|---|---|
--status <working|idle|stopped> | Filter by status |
--all | Include ephemeral (claude-<pid>) sessions such as main |
actor list --all --status working
actor show
Show details (workspace, agent, config, status, timestamps) for one session.
Pass --host <PEER> for a session on a remote host.
actor show <NAME>
actor new
Create a new session; with --prompt, also start it.
| Flag | Meaning |
|---|---|
<NAME> | Session name (positional, required) |
--prompt <TEXT> | Seed task; also starts the session |
--agent <claude|codex> | Agent to run |
--role <NAME> | Apply a role |
--dir <PATH> | Base directory for the worktree (absolute) |
--base <BRANCH> | Branch to fork the worktree from |
--no-worktree | Run in --dir directly, no worktree |
--arg <ARG> | Forward a raw argument to the agent (repeatable) |
--use-subscription <true|false> | Subscription vs. API-key auth |
--host <PEER> | Run on a trusted remote host — EndpointId or name (see Remote Hosts) |
actor new reviewer --role reviewer --prompt "Review src/auth/ for bugs."
actor run
Send a prompt to an existing session. Returns immediately; the session runs
in the background. If it's mid-turn, the prompt is queued behind the current
turn. Pass --host <PEER> for a session on a remote host.
actor run <NAME> <PROMPT>
actor stop
Interrupt the session's current turn. Keeps the agent alive. Pass
--host <PEER> for a session on a remote host.
actor stop <NAME>
actor discard
Discard a session: delete its definition and remove its worktree (the branch is kept). Refused if the worktree has uncommitted changes.
| Flag | Meaning |
|---|---|
--force | Bypass a failing on-discard hook (incl. the git-safety default) |
--host <PEER> | Discard a session on a trusted remote host |
actor discard <NAME> --force
actor logs
Read a session's transcript — user/assistant text, tool calls, and results.
| Flag | Meaning |
|---|---|
--tail <N> | Show only the last N messages (default: all) |
actor logs <NAME> --tail 20
actor servers
Peer trust for cross-host sessions (over iroh). See Remote Hosts.
actor servers list # self (with your EndpointId) + trusted peers
actor servers trust <ENDPOINT_ID> # trust a peer; --name <label> to label it
actor servers untrust <ENDPOINT_ID> # revoke trust (or pass its NAME)
trust / untrust take the peer's EndpointId (64 hex — its iroh public
key, confirmed out of band) or, for a peer already listed, its name. Trust is
mutual: sessions cross only once each daemon trusts the other.
actor roles
List roles defined in your settings.kdl files.
actor roles
actor status
Local daemon liveness, version, and pid (auto-spawns the daemon if needed).
actor status
actor mcp
Advanced: re-exec the bundled MCP server, used to wire actor.sh's tools into an external MCP host (the main session does this for you automatically).
actor mcp --for claude