CLI Reference

Complete reference for the actor CLI. Each section covers one subcommand: its flags, defaults, and a minimal example. Run actor --help or actor <cmd> --help for the in-terminal version.

actor main

Launch the orchestrator session. Resolves the main role from settings.kdl, takes its prompt as --append-system-prompt, and execs claude with the actor channel enabled. Trailing arguments are forwarded to the agent CLI verbatim.

The built-in main role ships as the main actor. Override it with a role "main" { ... } block in settings.kdl to swap in your own prompt or agent. Today only agent "claude" is supported on this command; other agents fail with a clear error.

actor main                                # open an interactive orchestrator session
actor main "kick off the refactor"        # one-shot
actor main --model opus                   # forward flags to claude

actor new

Create a new actor. If a prompt is given (positional or piped via stdin), the actor is also run immediately after creation.

actor new my-feature                                      # create worktree, no run
actor new my-feature "fix the nav bar"                    # create and run
actor new my-feature --role qa                            # apply a saved role
actor new my-feature --no-use-subscription                # pass API keys through
actor new my-feature --no-worktree                        # use current directory
actor new my-feature --base develop                       # branch off develop
actor new my-feature --config effort=max --model opus     # set agent config at creation
echo "fix it" | actor new my-feature                      # piped prompt

--config keys collide-check against the agent’s ACTOR_DEFAULTS whitelist; passing an actor-key (e.g. use-subscription) through --config is rejected with a hint pointing at the dedicated flag.

actor run

Run an existing actor with a prompt.

actor run fix-nav "continue fixing"                       # one-shot
actor run fix-nav --config model=opus "one-off"           # temporary config
actor run fix-nav -i                                      # resume interactively
echo "fix it" | actor run fix-nav                         # piped prompt

The CLI prints the agent’s response to stdout and propagates a non-zero exit code if the run failed.

actor list

List actors. Optional status filter.

actor list                                                # all actors
actor list --status running                               # only running

actor roles

List roles defined in settings.kdl (built-in main plus user-level and project-level roles).

actor roles

actor show

Show full details for an actor, including recent runs.

actor show my-feature
actor show my-feature --runs 20
actor show my-feature --runs 0

actor logs

View agent session output.

actor logs my-feature
actor logs my-feature --verbose
actor logs my-feature --watch

actor stop

Kill the running agent for an actor. The actor row stays; only the live process is terminated.

actor stop my-feature

actor config

View or update an actor’s saved config. With no pairs, prints the current config; with one or more KEY=VALUE pairs, updates those keys. Updates take effect on the next run.

actor config my-feature                                   # view
actor config my-feature model=opus                        # update one key
actor config my-feature model=sonnet effort=max           # update several

actor mcp

Start the MCP server over stdio. This is the entrypoint Claude Code uses to spawn the actor MCP — you typically don’t run it by hand.

actor mcp --for claude-code

actor watch

Open the dashboard TUI. Animated splash by default; use --no-animation over slow links.

actor watch                                               # local TUI
actor watch --no-animation                                # skip splash

actor discard

Remove an actor from the database. The worktree directory stays on disk and the underlying git branch is left in place — recover the name later by running git branch -D <name> in the source repo if needed.

actor discard my-feature
actor discard my-feature --force

actor setup

Install (or reinstall) an integration. Idempotent — safe to re-run.

actor setup --for claude-code                             # user-wide install
actor setup --for claude-code --scope project             # project-local
actor setup --for claude-code --name actor-dev            # alternate MCP name
actor setup --for omarchy                                 # theme-set hook
actor setup --for omarchy --uninstall                     # remove the hook

actor update

Refresh deployed skill files after upgrading actor-sh. Use setup for a fresh install; update is a lightweight refresh that keeps existing registration in place.

actor update                                              # refresh user-wide install
actor update --scope project                              # refresh project-local

actor –version

Print the installed actor-sh version.

actor --version
actor -V

See also

• MCP tool reference — the surface the orchestrator sees.
• Config keys — every key per agent.
• Roles — how roles wire into actor new and actor main.