07 - CLI Reference

Quick-reference for all Agent Orchestrator CLI commands.

Entry Points

Binary	Description
`orchestratord`	gRPC daemon — server + embedded workers
`orchestrator`	CLI client — lightweight gRPC calls over Unix socket

The daemon holds all state (engine, DB, task queue). The CLI is a thin RPC client.

Global Options

Flag	Description
`-v, --verbose`	Enable verbose output
`-h, --help`	Print help
`-V, --version`	Print version
`--control-plane-config <path>`	Override control-plane client config (env: `ORCHESTRATOR_CONTROL_PLANE_CONFIG`)

Command Aliases

Command	Alias
`apply`	`ap`
`get`	`g`
`describe`	`desc`
`delete`	`rm`
`event`	`ev`
`task`	`t`
`task list`	`task ls`
`task create`	`task new`
`task info`	`task get`
`task logs`	`task log`
`task delete`	`task rm`
`check`	`ck`
`debug`	`dbg`
`store list`	`store ls`
`agent`	`ag`
`agent list`	`agent ls`
`trigger`	`tg`
`secret key list`	`secret key ls`
`db migrations list`	`db migrations ls`

Initialization & Configuration

init

Create runtime directories and SQLite schema.

bash

orchestrator init

apply

Load resources from a YAML manifest into the database.

bash

# From file
orchestrator apply -f manifest.yaml

# From stdin
cat manifest.yaml | orchestrator apply -f -

# Dry-run (validate only)
orchestrator apply -f manifest.yaml --dry-run

# Project-scoped apply
orchestrator apply -f manifest.yaml --project my-project

check

Preflight validation: cross-reference agents, workflows, and templates.

bash

orchestrator check
orchestrator check --workflow self-bootstrap
orchestrator check --project my-project
orchestrator check -o json

Flag	Description
`--workflow <WORKFLOW>`	Check a specific workflow
`-o, --output`	Output format: table (default), json, yaml
`-p, --project`	Project filter

Resource Queries

get

List resources (kubectl-style).

bash

orchestrator get workspaces
orchestrator get agents
orchestrator get workflows

# Output format
orchestrator get agents -o json
orchestrator get agents -o yaml

# Project-scoped query
orchestrator get agents --project my-project

# Label selector
orchestrator get agents -l env=dev

Flag	Description
`-o, --output`	Output format: table (default), json, yaml
`-l, --selector`	Label selector filter
`-p, --project`	Project filter

describe

Detailed view of a single resource.

bash

orchestrator describe workspace/default
orchestrator describe agent/coder

# Project-scoped
orchestrator describe agent/my-agent --project my-project

delete

Delete a resource by kind/name.

bash

orchestrator delete workspace/my-ws --force
orchestrator delete agent/old-agent --force

# Dry-run
orchestrator delete agent/old-agent --dry-run

# Project-scoped
orchestrator delete agent/old --force --project my-project

Flag	Description
`-f, --force`	Force delete without confirmation
`--dry-run`	Show what would be deleted
`-p, --project`	Project filter

Task Lifecycle

task create

bash

orchestrator task create \
  --name "my-task" \
  --goal "Implement feature X" \
  --workflow self-bootstrap \
  --project my-project \
  --workspace default \
  --target-file docs/qa/01-test.md    # can specify multiple times

# Step filtering: only run specific steps from the workflow
orchestrator task create \
  --workflow sdlc --project my-project \
  --step fix \
  --set ticket_paths=docs/ticket/T-0042.md

# Multiple steps (executed in workflow order)
orchestrator task create \
  --workflow sdlc --step plan --step implement

Flag	Description
`-n, --name`	Task name
`-g, --goal`	Task goal/description
`-p, --project`	Project ID
`-w, --workspace`	Workspace ID
`-W, --workflow`	Workflow ID
`-t, --target-file`	Target files (repeatable)
`--no-start`	Create without auto-starting
`-S, --step`	Execute only specified step IDs (repeatable)
`--set`	Inject pipeline variable as `key=value` (repeatable)

run

Synchronous step execution — creates a task, follows logs, and exits with status code.

bash

# Synchronous execution with step filter
orchestrator run \
  --workflow sdlc --step fix \
  --set ticket_paths=docs/ticket/T-0042.md

# Background mode (equivalent to task create)
orchestrator run --workflow sdlc --step fix --detach

# Direct assembly mode: execute a StepTemplate without a workflow
orchestrator run \
  --template fix-ticket \
  --agent-capability fix \
  --set ticket_paths=docs/ticket/T-0042.md

Flag	Description
`-W, --workflow`	Workflow ID (required unless `--template` is specified)
`-S, --step`	Execute only specified step IDs (repeatable)
`--set`	Inject pipeline variable as `key=value` (repeatable)
`-p, --project`	Project ID
`-w, --workspace`	Workspace ID
`-t, --target-file`	Target files (repeatable)
`--detach`	Run in background (print task ID and return)
`--template`	StepTemplate name (direct assembly mode)
`--agent-capability`	Agent capability for direct assembly mode
`--profile`	ExecutionProfile override for direct assembly mode

task list / info

bash

orchestrator task list
orchestrator task list -o json
orchestrator task list --project my-project    # filter by project
orchestrator task list --status running        # filter by status
orchestrator task list -v                      # verbose output

orchestrator task info <task_id>
orchestrator task info <task_id> -o yaml

Flag (list)	Description
`-s, --status`	Filter by task status
`-p, --project`	Project filter
`-o, --output`	Output format: table (default), json, yaml
`-v, --verbose`	Verbose output

task recover

Recover orphaned running items (e.g. after a crash).

bash

orchestrator task recover <task_id>

task start / pause / resume

bash

orchestrator task start <task_id>
orchestrator task start --latest             # start the most recent task

orchestrator task pause <task_id>
orchestrator task resume <task_id>
orchestrator task resume <task_id> --reset-blocked   # reset blocked items back to unresolved

Flag (start)	Description
`-l, --latest`	Start the latest task

Flag (resume)	Description
`--reset-blocked`	Reset blocked items back to unresolved

task logs / watch / trace

bash

# View execution logs
orchestrator task logs <task_id>
orchestrator task logs <task_id> --follow --timestamps
orchestrator task logs <task_id> --tail 50

# Live watch (auto-refreshing status panel)
orchestrator task watch <task_id>
orchestrator task watch <task_id> --interval 5

# Execution trace with anomaly detection
orchestrator task trace <task_id>
orchestrator task trace <task_id> --verbose --json

Flag (logs)	Description
`-f, --follow`	Follow logs in real-time
`-n, --tail`	Number of lines to show (default: 100)
`--timestamps`	Include timestamps

Flag (watch)	Description
`--interval`	Update interval in seconds (default: 2)
`--timeout <SECONDS>`	Exit after N seconds (0 = no timeout, default: 0)

Flag (trace)	Description
`--verbose`	Verbose trace output
`--json`	JSON output format

task retry

Retry a failed task item.

bash

orchestrator task retry <task_item_id> [--force]

task delete

bash

orchestrator task delete <task_id> --force
orchestrator task delete <id1> <id2> <id3> --force   # multiple task IDs
orchestrator task delete --all --force                # delete all tasks
orchestrator task delete --all --status completed     # delete all with status filter
orchestrator task delete --all --project my-project   # delete all in a project

Flag	Description
`-f, --force`	Force delete without confirmation
`--all`	Delete all tasks
`--status <STATUS>`	Filter by status (used with `--all`)
`--project <PROJECT>`	Filter by project (used with `--all`)

Manifest

bash

# Validate a manifest file
orchestrator manifest validate -f manifest.yaml
orchestrator manifest validate -f manifest.yaml --project my-project

# Export all resources as manifest documents
orchestrator manifest export [-o yaml|json]

Flag (validate)	Description
`-f, --file`	Manifest file (required)
`-p, --project`	Project filter

Secret Key Management

bash

orchestrator secret key status [-o json]
orchestrator secret key list [-o json]
orchestrator secret key rotate [--resume]
orchestrator secret key revoke <key_id> [--force]
orchestrator secret key history [-n <limit>] [--key-id <id>] [-o json]

Database Operations

bash

orchestrator db status [-o json]
orchestrator db migrations list [-o json]

Project Cleanup

Use orchestrator delete project/<id> --force for project cleanup.

Project Management

Project isolation is native — use --project on apply, get, describe, delete, task create, task list, and store commands.

bash

# Apply resources to a project scope
orchestrator apply -f manifest.yaml --project my-project

# Explicitly prune resources omitted from the manifest
orchestrator apply -f manifest.yaml --project my-project --prune

# Query project-scoped resources
orchestrator get agents --project my-project

# Delete a project and all its data (tasks, items, runs, events, config)
orchestrator delete project/<project> --force

Default apply is merge-only: resources omitted from the manifest are preserved. Use --prune only when you want omitted resources of the same applied kinds to be deleted within the target project.

Persistent Store

bash

orchestrator store get <store_name> <key>
orchestrator store put <store_name> <key> <value>
orchestrator store put <store_name> <key> <value> --task-id <id>
orchestrator store delete <store_name> <key>
orchestrator store list <store_name>
orchestrator store list <store_name> --limit 50 --offset 10
orchestrator store prune <store_name>

# Project-scoped store
orchestrator store get <store_name> <key> --project my-project
orchestrator store put <store_name> <key> <value> --project my-project

Flag (list)	Description
`-l, --limit`	Result limit (default: 100)
`--offset`	Result offset (default: 0)
`-o, --output`	Output format: table (default), json, yaml
`-p, --project`	Project filter

Flag (put)	Description
`-t, --task-id`	Associated task ID
`-p, --project`	Project filter

Agent Lifecycle

Manage agent scheduling state (cordon, drain, uncordon).

bash

# List agents with lifecycle state
orchestrator agent list
orchestrator agent list --project my-project -o json

# Cordon: mark agent as unschedulable (no new work dispatched)
orchestrator agent cordon <agent_name>
orchestrator agent cordon <agent_name> --project my-project

# Uncordon: mark a cordoned agent as schedulable again
orchestrator agent uncordon <agent_name>

# Drain: cordon + wait for in-flight work to complete
orchestrator agent drain <agent_name>
orchestrator agent drain <agent_name> --timeout 60

Subcommand	Description
`list`	List agents and their lifecycle state
`cordon`	Mark an agent as unschedulable
`uncordon`	Mark a cordoned agent as schedulable again
`drain`	Cordon + wait for in-flight work to complete

Flag	Description
`-p, --project`	Project filter
`-o, --output` (list only)	Output format: table (default), json, yaml
`--timeout` (drain only)	Timeout in seconds; force-drain after this duration

Daemon Lifecycle

bash

orchestrator daemon status                    # show daemon PID and status
orchestrator daemon stop                      # send SIGTERM to daemon
orchestrator daemon maintenance --enable      # block new task creation
orchestrator daemon maintenance --disable     # allow task creation again

Event Lifecycle

bash

orchestrator event stats                      # show event table statistics
orchestrator event cleanup                    # clean up old events
orchestrator event cleanup --older-than 30    # events older than N days (default 30)
orchestrator event cleanup --dry-run          # preview without deleting
orchestrator event cleanup --archive          # archive to JSONL before deleting

Trigger Lifecycle

bash

orchestrator trigger suspend <name>           # suspend a trigger
orchestrator trigger resume <name>            # resume a suspended trigger
orchestrator trigger fire <name>              # manually fire a trigger once
orchestrator trigger fire <name> --payload '{"key":"value"}'   # fire with JSON payload

All trigger subcommands accept the --project flag for project-scoped operation.

Debug & System

bash

orchestrator debug                   # inspect internal state
orchestrator debug --component config  # show active config
orchestrator version                 # build version + git hash
orchestrator version --json          # JSON version output
orchestrator check                   # preflight validation
orchestrator check -o json           # structured check output

Output Formats

Most get and info commands support -o for output format:

bash

-o json    # JSON output
-o yaml    # YAML output
# (default) # table output

Daemon (C/S Mode)

orchestratord

The daemon binary that runs the gRPC server and embedded background workers.

bash

# Start in foreground (recommended for development)
./target/release/orchestratord --foreground

# With multiple workers
./target/release/orchestratord --foreground --workers 3

# TCP bind (for remote access)
./target/release/orchestratord --foreground --bind 0.0.0.0:50051

Flag	Description
`--foreground`, `-f`	Run in foreground (don't daemonize)
`--bind <addr>`	TCP bind address (default: Unix socket)
`--workers <N>`	Number of background workers (default: 1)
`--insecure-bind <addr>`	Insecure TCP bind for development (feature-gated: `dev-insecure`)
`--control-plane-dir <DIR>`	Control plane certificate directory
`--event-retention-days <DAYS>`	Days to retain events (default: 30, 0 = disabled)
`--event-cleanup-interval-secs <SECS>`	Cleanup sweep interval in seconds (default: 3600)
`--event-archive-enabled`	Archive events to JSONL before cleanup
`--event-archive-dir <DIR>`	Override event archive directory
`--stall-timeout-mins <MINS>`	Minutes before a running item is considered stalled (default: 30, 0 = disabled)
`--webhook-bind <ADDR>`	Bind address for HTTP webhook server (default: `127.0.0.1:19090`, `none` to disable). Non-loopback addresses require a secret.
`--webhook-secret <SECRET>`	Shared secret for webhook HMAC-SHA256 verification (env: `ORCHESTRATOR_WEBHOOK_SECRET`)
`--webhook-allow-unsigned`	Allow webhook on non-loopback without signature verification (env: `ORCHESTRATOR_WEBHOOK_ALLOW_UNSIGNED`)

control-plane issue-client

Issue client TLS materials for connecting to the daemon's control plane:

bash

orchestratord control-plane issue-client \
  --bind <addr> --subject <name> [--role <role>]

Files created:

PID: ~/.orchestratord/daemon.pid
Socket: ~/.orchestratord/orchestrator.sock

daemon management

bash

./target/release/orchestratord --foreground --workers 2   # foreground (recommended)
nohup ./target/release/orchestratord --foreground &       # background via nohup
orchestrator daemon stop                                  # graceful SIGTERM

C/S CLI command surface

All commands connect to the daemon via Unix socket:

bash

# Resource management (--project for project scope)
orchestrator apply -f manifest.yaml [--project <id>] [--dry-run]
orchestrator get <resource> [-o json|yaml] [--project <id>]
orchestrator describe <kind/name> [--project <id>]
orchestrator delete <kind/name> --force [--project <id>]

# Task lifecycle
orchestrator task create --name X --goal Y [--project <id>] [--workflow Z] [--step S] [--set k=v]
orchestrator run --workflow Z [--step S] [--set k=v]          # synchronous execution
orchestrator run --template T --agent-capability C [--set k=v] # direct assembly mode
orchestrator task list [-o json] [--project <id>] [--status <s>]
orchestrator task info <id> [-o json]
orchestrator task start <id>
orchestrator task pause <id>
orchestrator task resume <id>
orchestrator task logs <id> [--tail N] [--follow]
orchestrator task watch <id>
orchestrator task trace <id> [--verbose]
orchestrator task retry <item_id> [--force]
orchestrator task delete <id> --force

# Agent lifecycle
orchestrator agent list [--project <id>] [-o json|yaml]
orchestrator agent cordon <agent_name> [--project <id>]
orchestrator agent uncordon <agent_name> [--project <id>]
orchestrator agent drain <agent_name> [--project <id>] [--timeout <secs>]

# Project cleanup
orchestrator delete project/<id> --force

# Store (--project for project scope)
orchestrator store put <store> <key> <value> [--project <id>]
orchestrator store get <store> <key> [--project <id>]
orchestrator store list <store> [-o json] [--project <id>]
orchestrator store delete <store> <key> [--project <id>]
orchestrator store prune <store> [--project <id>]

# Manifest
orchestrator manifest validate -f <file>
orchestrator manifest export [-o yaml|json]

# Secret key management
orchestrator secret key status|list|rotate|revoke|history

# Database
orchestrator db status [-o json]
orchestrator db migrations list [-o json]

# System
orchestrator version
orchestrator debug [--component config]
orchestrator check [-o json] [--workflow <w>]
orchestrator init [<root>]

Resource Metadata

All resources support metadata.labels (key-value pairs for categorization and label-selector queries) and metadata.annotations (arbitrary key-value metadata). Both are optional.

yaml

metadata:
  name: my-resource
  labels:
    env: dev
    team: platform
  annotations:
    note: "created for sprint 12"

Structured Agent Output

Agents must produce JSON on stdout conforming to this schema:

json

{
  "confidence": 0.95,
  "quality_score": 0.9,
  "artifacts": [
    {
      "kind": "analysis",
      "findings": [
        {
          "title": "finding-name",
          "description": "details",
          "severity": "info"
        }
      ]
    }
  ]
}

Field	Type	Description
`confidence`	`float`	Agent's confidence in the result (0.0–1.0)
`quality_score`	`float`	Quality assessment (0.0–1.0)
`artifacts`	`array`	Structured output artifacts
`artifacts[].kind`	`string`	`analysis`, `code_change`, etc.
`artifacts[].findings`	`array`	List of findings with title/description/severity
`artifacts[].files`	`array`	List of modified files (for code_change)

This output is parsed into AgentOutput and used for prehook variable injection (qa_confidence, qa_quality_score) and finalize rule evaluation.

07 - CLI Reference ​

Entry Points ​

Global Options ​

Command Aliases ​

Initialization & Configuration ​

init ​

apply ​

check ​

Resource Queries ​

get ​

describe ​

delete ​

Task Lifecycle ​

task create ​

run ​

task list / info ​

task recover ​

task start / pause / resume ​

task logs / watch / trace ​

task retry ​

task delete ​

Manifest ​

Secret Key Management ​

Database Operations ​

Project Cleanup ​

Project Management ​

Persistent Store ​

Agent Lifecycle ​

Daemon Lifecycle ​

Event Lifecycle ​

Trigger Lifecycle ​

Debug & System ​

Output Formats ​

Daemon (C/S Mode) ​

orchestratord ​

control-plane issue-client ​

daemon management ​

C/S CLI command surface ​

Resource Metadata ​

Structured Agent Output ​

07 - CLI Reference

Entry Points

Global Options

Command Aliases

Initialization & Configuration

init

apply

check

Resource Queries

get

describe

delete

Task Lifecycle

task create

run

task list / info

task recover

task start / pause / resume

task logs / watch / trace

task retry

task delete

Manifest

Secret Key Management

Database Operations

Project Cleanup

Project Management

Persistent Store

Agent Lifecycle

Daemon Lifecycle

Event Lifecycle

Trigger Lifecycle

Debug & System

Output Formats

Daemon (C/S Mode)

orchestratord

control-plane issue-client

daemon management

C/S CLI command surface

Resource Metadata

Structured Agent Output