Commands

Complete choirctl command reference. choirctl is a stateless CLI that communicates with a running choird instance.

System Setup

choirctl init

First-time setup. Creates ~/.choir.d/ directory structure, generates a skeleton config.json, generates secrets.json (mode 0600), creates user-local runtime directories (including ~/.choir.d/socks/), and prints setup instructions.

choirctl init

Does NOT create Postgres schemas (the user must ensure the database exists; choird creates per-agent schemas on first startup).

Daemon Service (Local)

These commands manage the local choird systemd user service via systemctl --user. They do not use choird RPC.

choirctl daemon start

Start the choird service.

choirctl daemon start

choirctl daemon stop

Stop the choird service.

choirctl daemon stop

choirctl daemon restart

Restart the choird service.

choirctl daemon restart

choirctl daemon enable

Enable the service to start automatically for the user.

choirctl daemon enable

choirctl daemon disable

Disable automatic startup for the user.

choirctl daemon disable

choirctl daemon status

Show choird unit status (load, active, sub, enabled state, and fragment path).

choirctl daemon status

Use --unit to target a different user unit:

choirctl daemon status --unit my-choird.service

choirctl daemon logs

Read logs from the local choird systemd user service via journalctl --user.

choirctl daemon logs
choirctl daemon logs --lines 200
choirctl daemon logs --follow

Agent Lifecycle

choirctl agent init <agent-id>

Scaffold a new agent with placeholder config.

choirctl agent init my-agent

Creates an entry in config.json with placeholder values (repo URL, defaults). Scaffolds the per-agent git repo with skeleton files (Dockerfile, identity/SOUL.md, identity/SOUL-CORE.md, empty tools/ and skills/ directories). Does not build or start the agent.

choirctl agent base init

Scaffolds the shared global repo under ~/.choir.d/repos/global/ with:

• Dockerfile.base
• identity/USER.md
• identity/SOUL.md
• identity/SOUL-CORE.md
• empty tools/ and skills/

Initializes a local git repo if needed. This scaffold is meant to be pushed to a remote, then referenced by global_repo.url and global_repo.ref in config.json.

choirctl agent base build

Builds the local choir-base image from the configured global_repo.

• fetches/checks out the configured global repo
• injects the host’s choir-agent binary into a temporary build context
• builds Dockerfile.base
• tags the result as choir-base

choirctl agent build <agent-id> automatically runs this first when the fetched global_repo HEAD has changed since the last successful base build.

choirctl agent list

List all configured agents and their current status.

choirctl agent list

choirctl agent start <agent-id> [flags]

Start an agent container and begin a session.

choirctl agent start my-agent --dm=admin
choirctl agent start my-agent --workspace=scratch --llm=gpt4o --dm=work-dm

Flags (override agent defaults):

choird validates that all named resources exist and that exclusive resources are not already leased. Rejects start if any validation fails.

choirctl agent stop <agent-id>

Graceful termination. The agent completes its current safe point, generates a session summary, flushes all events to Postgres, and exits. The session is recoverable on next start.

choirctl agent stop my-agent

choirctl agent restart <agent-id>

Stop then start with the same image and resource bindings.

choirctl agent restart my-agent

choirctl agent status <agent-id>

Detailed status: lane states, budgets, active skill, resource bindings, config version, uptime.

choirctl agent status my-agent

choirctl agent build <agent-id>

Build a new or updated agent Docker image. Fetches global and per-agent repos, merges artifacts, builds the image, and tags it. Does not start or restart the agent.

choirctl agent build my-agent

choirctl agent update <agent-id>

Build (if needed) + graceful stop + start with new image. Session is persisted before the old container exits and restored after the new one starts.

choirctl agent update my-agent

choirctl agent update-all

Build and redeploy all agents. Running agents are updated sequentially (stop + start with new image). Stopped agents get a new image but are not started.

choirctl agent update-all

Session

choirctl session list [agent-id]

List active and recent sessions, optionally filtered by agent.

choirctl session list
choirctl session list my-agent

choirctl session events <session-id>

Stream the session event log.

choirctl session events sess-abc123

choirctl session cores <session-id>

List active core jobs in the session. Shows job name, ID, state, and step count.

choirctl session cores sess-abc123

choirctl session cancel <session-id>

Cancel a core job. When multiple cores are running, specify the job name.

choirctl session cancel sess-abc123

choirctl session compact <session-id>

Trigger working memory compaction for the session.

choirctl session compact sess-abc123

Model Switching

Model and voice profile changes are hot-reloadable – the agent picks up the new settings on its next LLM call or TTS invocation. Changes are transient: on agent restart, the agent reverts to its defaults.

choirctl model list

List named LLM models and TTS providers from config.

choirctl model list

choirctl model get <agent-id>

Show the current LLM model for the agent.

choirctl model get my-agent

choirctl model set <agent-id> --llm=<name>

Switch the text generation model for a running agent.

choirctl model set my-agent --llm=gpt4o

choirctl voice list

List named voice profiles from config.

choirctl voice list

choirctl voice get <agent-id>

Show the current voice profile for the agent.

choirctl voice get my-agent

choirctl voice set <agent-id> <name>

Switch the voice profile for a running agent.

choirctl voice set my-agent narrator

Configuration (Two-Phase)

choirctl config validate

Validate the local on-disk config.json and secrets.json without talking to choird. This checks config cross-references, agent ID validity, normalized Postgres schema-name collisions, strict secrets.json parsing, and that every referenced secret exists.

choirctl config validate

Use --config-dir to validate a different local Choir directory:

choirctl config validate --config-dir=/path/to/.choir.d

choirctl config load

Read ~/.choir.d/ into choird, validate, and stage. Fetches latest commits from all repos. Either the entire snapshot validates and is staged, or nothing is staged.

choirctl config load

choirctl config diff

Show the diff between staged and running config. Changes are categorized:

• [hot-reload]: Applied via config apply (models, voice profiles, tunable defaults).
• [restart-required]: Applied via agent update (tools, skills, identity, Dockerfiles).

choirctl config diff

choirctl config apply

Push hot-reloadable changes to running agents. Bumps config_version; agents pick it up via heartbeat.

choirctl config apply

choirctl config show

Show the current running configuration.

choirctl config show

Approvals

choirctl approval list

List all pending approval requests.

choirctl approval list

choirctl approval show <id>

Show approval detail: what was requested, by which agent, when.

choirctl approval show ap-12345

choirctl approval approve <id>

Approve a pending request.

choirctl approval approve ap-12345

choirctl approval reject <id>

Reject a pending request.

choirctl approval reject ap-12345

Workspace

choirctl workspace list

List all workspaces, their host paths, and current lease holders.

choirctl workspace list

choirctl workspace reset <workspace-name>

Delete workspace contents. If an agent holds a lease on the workspace, the agent is stopped first.

choirctl workspace reset scratch

Secrets

choirctl secret list

List secret names only. Never displays values.

choirctl secret list

choirctl secret set <name> [secret]

Set or update a secret value. If [secret] is provided, it is used directly. Otherwise, the value is read from stdin.

• Local mode (no --endpoint): edits ~/.choir.d/secrets.json directly.
• Remote mode (--endpoint): sends the update to remote choird, which edits host-side secrets.json.

choirctl secret set openrouter-key sk-new-key
echo 'sk-new-key' | choirctl secret set openrouter-key

choirctl secret delete <name>

Delete a secret immediately from secrets.json.

choirctl secret delete old-key

choirctl secret apply

Instruct choird to reload ~/.choir.d/secrets.json and push a secret refresh signal to all running agents. This is all-or-nothing at choird apply time; failures are reported back to choirctl.

choirctl secret apply

Observability

choirctl logs <agent-id|choird>

Print the current log file contents (snapshot), then continue streaming new lines (like tail -f). Ctrl+C stops streaming.

choirctl logs my-agent
choirctl logs choird

choirctl status

System overview: choird health, Postgres connection status, running agents summary.

choirctl status

For gateway (Telegram) command equivalents, see Gateway.