CLI Reference

Namespaces

orch task     list|add|get|status|route|run|retry|reroute|unblock|attach|live|kill
              publish|cost|tree|deps|logs|log|history|runs|close|watch|inspect
              events|session
orch service  start|stop|restart|status|install|uninstall|doctor|prune
orch job      list|add|remove|enable|disable|tick|run|cron
orch plan     [file] | import
orch project  list|add|remove|move|board
orch stats    overview|metrics|cost|dashboard
orch cooldown list|clear
orch chat     [message…] | history | stats

Visible top-level commands: init, log, nodes, progress, commit, config, stream, chat, task, job, plan, service, project, cooldown, stats, notify.

orch serve is hidden. It runs the engine in the foreground, and the launchd and systemd units run it. orch progress --done "..." [--left "..."] [--state "..."] records what a task step finished and commits it, and the service pushes. orch nodes lists the cluster's machines, see Cluster.

Init

orch init
orch init --repo owner/repo

orch init finds the agent CLIs on PATH and whether each is logged in, and checks gh auth. It asks for one repository, writes ~/.orch/config.yml with only the values that differ from the defaults, and starts the service. It then prints orch plan <file>. --repo OWNER/REPO skips the question. From a git checkout, origin is the default.

Task Commands

Task commands that take an id accept a bare number, owner/repo#N, repo#N, internal:N, or internal-N. Inside a project directory a bare number is that project's GitHub issue. If the same number matches more than one task and you are not in a project directory, the command names both forms and stops.

orch task add "title" -b "body" -l label1 -l label2   # create a task
orch task add "title" --depends-on 12 --depends-on owner/other#4
                                                       # create a GitHub issue blocked by those issues
orch task list                                         # list tasks for current project
orch task list -g                                      # list across all projects
orch task tree [id]                                    # show parent-child tree
orch task tree --deps                                  # show blocked-by edges
orch task deps <id>                                    # what this task waits on, and what waits on it
orch task get <id>                                     # task details
orch task status                                       # status summary for current project
orch task route <id>                                   # (re-)route a task
orch task run [id]                                     # run a specific task (or next routed)
orch task retry <id> [--agent X --model Y]             # reset to new, optionally forcing routing. Done is terminal: a done task is refused
orch task reroute <id> --agent X --model Y             # force a new agent/model
orch task unblock <id> | all                           # reset blocked tasks to new. A task that is only waiting stays waiting, a done task is refused
orch task attach <id>                                  # attach to the agent's tmux session
orch task live                                         # list active agent tmux sessions
orch task kill <id>                                    # kill a running agent tmux session
orch task publish <id> [-l label1]                     # promote internal task to GitHub
orch task cost <id>                                    # token cost breakdown
orch task logs <id>                                    # post-mortem / saved logs for a task
orch task log <id> [--limit N] [--json]                # activity timeline
orch task history <id>                                 # routing history / attempts
orch task runs <id> [--verbose]                        # full run audit (stdout/stderr/response)
orch task close <id> [-n "note"]                       # mark done without running an agent
orch task watch <id>                                   # follow the agent's output live, with its review
orch task inspect <id>                                 # unified diagnostic view
orch stream [id]                                       # stream live output (all sessions if no id)
orch log -f --task <id>                                # stream one task through log

Note: orch task add does not take a -p/project flag — task creation always targets the current project (resolved from CWD or the .orch.yml config). To create tasks for another project, cd into it first, or use orch task publish to promote an internal task to GitHub.

Background Service

orch service install [--force]  # write the systemd user unit and enable it (Linux), --force overwrites an existing unit
orch service uninstall          # disable and remove the systemd user unit (Linux)
orch service start      # start background service
orch service stop       # stop background service
orch service restart    # restart service
orch service status     # show service status

With Homebrew:

brew services start orch    # start as launchd service
brew services stop orch
brew services restart orch

The service ticks every engine.tick_interval seconds (default 10s):

• Syncs GitHub issues and PR events (webhook or polling)
• Routes new tasks to agents (round-robin by default, LLM router with router.mode: llm)
• Dispatches routed tasks into tmux sessions in worktrees
• Runs due scheduled jobs (per-project)
• Recovers stuck tasks (no tmux session, age >10 min → reset to new, an in_review task without a review session → needs_review)

Stats & Status

orch stats dashboard        # full dashboard view (tasks, sessions, activity)
orch stats dashboard -g     # aggregate across all configured projects
orch task status            # show task counts for current project
orch stats metrics [--details] # task metrics summary (slow tasks, error dist.)
orch stats cost [--summary] # cost tracking and token usage
orch stats [--all] [--since 7d] # task throughput / per-project rollups (default window 24h)
orch stats overview [--all] # explicit overview subcommand
orch stats export [--repo owner/name] [--since 30d] [--out proof.json] # merged PRs per day, agent of each, hours from issue to merge
orch task events [--repo X] [--task ID] # tail task events live
orch log [N]                # tail server logs (last N lines)
orch log -f                 # follow service logs
orch service doctor [--fix] [--dry-run] [--full] # diagnose SQLite ↔ GitHub drift. A done task is reported, never moved out of done
orch service prune [--dry-run] # remove orphaned worktrees
orch cooldown list          # show active cooldowns and degraded agents
orch cooldown clear <key>   # clear a cooldown (claude or claude:sonnet) and that agent's degraded rate-limit window
orch cooldown clear --all   # clear every cooldown and mark every configured agent as cleared
orch task session export <id> [-a N] [-f markdown|json|raw] # export a task's session
orch notify "message"       # send a Telegram notification (uses config target by default)
orch config <key>           # read a live config value (dot-separated path)
orch config agents          # list installed agent CLIs

Channels

Channels are first-class: use chat platforms to interact with running tasks. Incoming messages in a bound thread are forwarded to the agent's tmux session (via tmux send-keys). New conversations can create internal tasks when sent to any configured channel. Live output from sessions is streamed to all bound channel threads with per-channel rate limiting and message splitting.

Project Commands

orch project add .                         # register the current directory
orch project add owner/repo                # bare clone + import issues
orch project add https://github.com/o/r    # same, from a URL
orch project add /path/to/repo             # register a local path
orch project list                          # list registered projects
orch project remove /path/to/repo          # remove a project from registry
orch project move old/slug new/slug        # re-key stored tasks after a repo transfer or rename
orch project board list                    # list GitHub Projects V2 boards
orch project board link <id>               # link a board
orch project board sync                    # discover field IDs
orch project board info                    # show board config
orch project board reconcile [--repo o/r]  # set label-managed board Status fields once, no agents start

Job Commands

orch job list                                              # list scheduled jobs
orch job add "0 9 * * *" "Daily report" -b "body"          # cron + title (positional)
orch job add "0 9 * * *" "Backup" -t bash -c "./backup.sh" # bash job
orch job remove <id>                                       # remove a job
orch job enable <id>                                       # enable a job
orch job disable <id>                                      # disable a job
orch job tick                                              # run one scheduler tick manually
orch job run <id>                                          # run a job immediately, ignoring schedule
orch job cron "0 9 * * *" [--since <ts>]                    # check if a cron expression matches now

Jobs can also be defined declaratively as markdown files under prompts/jobs/*.md (frontmatter: id, schedule, title, type, enabled, external, agent, command, dir). See Jobs.

Plan

orch plan docs/PLAN.md
orch plan docs/PLAN.md --yes
orch plan import docs/ROADMAP.md
orch plan import docs/ROADMAP.md --dry-run
orch plan import docs/ROADMAP.md --milestone M1
orch plan import docs/ROADMAP.md --milestone M4 --skip-unmet

orch plan <file> sends a free-form markdown plan to an agent, writes a roadmap next to the plan (PLAN.roadmap.md), prints the milestones, tasks and dependencies, and asks before creating issues. Nothing is created on GitHub until you say yes. --yes skips the question. A later run keeps the same task ids so import updates the same issues.

orch plan import reads a roadmap file and creates one GitHub issue per task. The title is the task id and the task title. The body holds the goal, scope and acceptance, a link to the heading on the default branch, and a hidden marker (<!-- orch-plan: M1-03 -->). A later import edits an issue only when the title, body or labels changed.

A milestone starts at ## M1. Milestone title. A task starts at ### M1-03 Task title. A later milestone can be a table whose header has Task and Depends on. The parser also reads Goal, Scope, Acceptance and Owner. A column outside that list is an error that names the column and the line. Write the Task cell as M1-03 Task title. A task with no title is an error that names the id and the line.

Depends on: M1-02, M1-05 is stored as GitHub blocked-by links. Depends on: none stores no link. An import drops a blocked-by link that the file no longer declares, and keeps a link to an issue outside the plan. An open blocked-by link holds the dependent task as waiting. Owner: human adds the owner:human and no-agent labels, so orch skips that issue. A task that leaves the file is listed and left open.

When the default branch has no GitHub Actions workflow, import adds a first task CI-01 Set up CI and tests and every other imported task is blocked by it. That task sets up the project skeleton, tests, a workflow that runs on push to the default branch, and shipcheck.toml when the repo already has that file. After the task merges and its checks pass on the default branch, orch creates a ruleset that requires those checks. If those checks fail or none start within 15 minutes, orch comments on the CI issue. Repeated failures route the task back or block it. If GitHub refuses the ruleset, orch leaves the CI issue open and comments so later tasks stay waiting until branch protection is on.

--dry-run prints every selected task, the links that would change, and the removed tasks. --milestone M1 imports that milestone only. A dependency outside the milestone links to the existing issue when one has the plan marker. When that issue does not exist yet, the import continues, the dependent issue body gets a blocked-external note, and orch holds the task as waiting. --skip-unmet skips creating those dependent issues. An id that is not in the roadmap is an error. Dispatch skips no-agent and owner:human.

Version

orch -V    # show CLI version

Service status lives under orch service status. When upgrading, run brew upgrade orch && brew services restart orch.

Chat

orch chat                           # interactive REPL
orch chat "what's running?"         # single message
orch chat --session ops             # use a named session profile
orch chat history                   # show recent messages
orch chat history --search "deploy" # search past conversations
orch chat stats                     # session cost statistics

Conversational control plane — talk to orch in natural language. Each message invokes a one-shot agent with context assembled from the live task state, memories, and recent summaries. Switch the model with /model agent:model inside the REPL.

Agent Management

orch config agents          # list available agents and their status

Logging