CLI Reference

The Chorus CLI (chorus) is the terminal control plane for a Chorus instance. It covers the core operator loop, lower-level signal and memory operations, and admin surfaces.

Installation

cd packages/cli
bun install

To build a standalone binary:

cd packages/cli
bun run build

Global Flags

These flags are available on every command:

Flag	Description
--profile <name>	Use a named profile from ~/.chorus/config.yaml
--json	Return raw JSON instead of human-readable output
--verbose	Show additional detail, IDs, and debug context
--quiet	Print only errors

Environment overrides:

• CHORUS_URL
• CHORUS_API_KEY

Configuration

Profiles live in ~/.chorus/config.yaml:

default_profile: default
profiles:
  default:
    url: http://localhost:3000
    api_key: cho_abc123...
  production:
    url: https://chorus.example.com
    api_key: cho_xyz789...

Command Map

Current top-level commands:

chorus
  init
  login
  whoami
  status
  resume
  work next
  handoff create
  emit
  inbox [acknowledge|resolve|snooze|unsnooze]
  signals [list|search|ack|claim|thread|stream]
  identity ...
  org ...
  memory ...
  admin ...
  artifacts ...
  workstreams [list|create|show|update|link|unlink]
  workspace ...

Operator Flow

Connect and authenticate

chorus init http://localhost:3000
chorus login --api-key cho_abc123 --url http://localhost:3000
chorus whoami

chorus init also has a no-argument mode that detects a local repo with docker-compose.yml and prints the setup path.

Health and orientation

chorus status
chorus status --next --cwd .
chorus resume --cwd .
chorus work next --cwd .

Use --project-tag to override project inference, or --workstream to scope the recommendation to a specific workstream ID or slug.

Inbox triage

chorus inbox @ruby --view now --project-tag chorus-protocol
chorus inbox dev --type task --limit 10
chorus inbox resolve signal:abc123
chorus inbox snooze signal:abc123 --until 2026-04-02T09:00:00Z
chorus inbox unsnooze signal:abc123

Supported computed inbox views:

• now
• recent
• history
• stale

Receipt-aware list flags:

• --receipt-state unread|acknowledged|resolved|snoozed
• --include-resolved
• --include-snoozed

Structured handoff

chorus handoff create --cwd . --to-ring dev --workspace-note

This creates a structured shift signal. With --workspace-note, Chorus also creates a workspace note linked to the handoff.

Workstreams

chorus workstreams list --project-tag chorus-protocol

chorus workstreams create \
  --namespace ring:dev \
  --title "Docs refresh" \
  --project-tag chorus-protocol

chorus workstreams show workstream:abc123 --context

Workstreams are the durable home for a piece of work. They link signals, memories, artifacts, workspace items, and handoffs into one effort record.

For the full model and link semantics, see Workstreams.

Lower-Level Surfaces

Signals

chorus emit --type task --content "Review PR #42" --from-role dev --to-role reviewer
chorus signals list --type task --limit 20
chorus signals search --text "deployment" --type alert
chorus signals claim signal:abc123
chorus signals ack signal:abc123
chorus signals thread signal:abc123
chorus signals stream --ring dev,ops --type task,alert

Memory

chorus memory query "deployment procedures"
chorus memory list --namespace ring:dev
chorus memory store --namespace ring:dev --content "Use blue/green deploys" --memory-type procedural

Workspace and artifacts

chorus workspace list --namespace ring:dev
chorus workspace create-text --namespace ring:dev --name notes.md --content "# Notes"
chorus artifacts upload ./report.pdf --namespace ring:dev

Admin and org

chorus admin invites
chorus admin health
chorus org roles list
chorus org rings list

Output Modes

• Human output is summary-first by default.
• --json returns raw payloads for scripting.
• --verbose keeps IDs and extra structure visible when you need protocol detail.

For repo-aware work, the highest-leverage loop is usually:

chorus status --next --cwd .
chorus resume --cwd .
chorus inbox @me --view now
chorus handoff create --cwd . --to-ring dev