CLI Reference
This page is the exhaustive command and flag reference for syndicate.
Normative source: cli_command_reference.md (entire document), with cross-checks against syndicatecode-docs-site-spec.md §4.25.
Global invocation model
Usage:
syndicate [global-flags] [command] [subcommand] [args] [flags]
Global flags:
| Flag | Type | Default | Description |
|---|---|---|---|
--workspace <path> | string | current working directory | Workspace root directory |
--config <path> | string | implementation default | Override config file path |
--session <id> | string | none | Scope command to a session where applicable |
--output <format> | enum | text | text, json, ndjson, table |
--verbose | bool | false | Emit additional diagnostics |
--quiet | bool | false | Suppress informational output |
--no-color | bool | false | Disable styled text output |
--no-tui | bool | false | Alias for --governance-suspended --governance-suspended-reason "headless_mode_implicit" |
syndicate (bare invocation)
Launches the TUI and begins or resumes a session.
Usage:
syndicate [--session <id>] [--workspace <path>] [--policy <bundle-path>]
Examples:
syndicate
syndicate --workspace /path/to/repo
syndicate --session 63d5e4f8-17a8-4f62-9568-16f299ec8bc8
syndicate session
Session lifecycle management.
Usage:
syndicate session list [--all]
syndicate session attach <session-id>
syndicate session terminate <session-id> [--force]
syndicate session inspect <session-id>
syndicate session export <session-id> --format json|ndjson [--out <path>]
Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
--all | bool | false | Include terminal session states in list |
--force | bool | false | Skip confirmation for terminate |
--format | enum | required for export | json or ndjson |
--out <path> | string | stdout | Write export to a file |
Examples:
syndicate session list
syndicate session inspect 63d5e4f8-17a8-4f62-9568-16f299ec8bc8
syndicate session export 63d5e4f8-17a8-4f62-9568-16f299ec8bc8 --format ndjson --out session.ndjson
syndicate run
Primary workflow entry point for TUI and headless execution.
Usage:
syndicate run [flags]
Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
--objective "<text>" | string | none | Workflow objective submitted as proposal |
--specialist <id> | string | none | Invoke a specific registered specialist |
| `--autonomy interactive | supervised | bounded` | enum |
| `--checkpoint always | policy | never` | enum |
--dry-run | bool | false | Run proposal, canonicalization, and policy evaluation only |
--no-tui | bool | false | Alias for governance-suspended headless mode |
--governance-suspended | bool | false | Suppress interactive checkpoints while keeping policy, permits, and audit active |
--governance-suspended-reason <text> | string | required when suspended | Required reason recorded on session-open evidence |
| `--output json | text | table` | enum |
--timeout <duration> | duration | implementation default | Maximum wall-clock runtime |
Exit codes:
| Code | Meaning |
|---|---|
| 0 | Workflow completed successfully |
| 1 | Workflow failed (execution error) |
| 2 | Workflow denied (policy or approval denial) |
| 3 | Workflow interrupted |
| 4 | Governance-suspended mode rejected at session start |
| 5 | Control plane unavailable |
Examples:
syndicate run --objective "stabilize flaky unit tests"
syndicate run --no-tui --output json --objective "summarize dependency drift"
syndicate run --governance-suspended --governance-suspended-reason "nightly CI" --objective "verify audit continuity"
syndicate run --dry-run --objective "evaluate write scope for formatting"
syndicate approve
Approval operations outside the TUI.
Usage:
syndicate approve list [--output json|table]
syndicate approve show <checkpoint-id>
syndicate approve decide <checkpoint-id> --approve|--deny [--scope once|session|policy] [--notes "<text>"] [--idempotency-key <key>]
Examples:
syndicate approve list
syndicate approve show cli-test
syndicate approve decide cli-test --approve --scope session --notes "reuse within this CI session"
syndicate grants
Reusable approval grant inspection, history, and revocation.
Usage:
syndicate grants list [--session <id>] [--output json|table]
syndicate grants history [--session <id>] [--output json|table]
syndicate grants revoke <grant-id|all> [--session <id>] [--reason "<text>"]
syndicate revoke-grant <grant-id>
Examples:
syndicate grants list --session 63d5e4f8-17a8-4f62-9568-16f299ec8bc8
syndicate grants history --session 63d5e4f8-17a8-4f62-9568-16f299ec8bc8 --output json
syndicate revoke-grant grant-abc123 --reason "trust downgraded"
syndicate policy
Policy validation, application, diffing, history, and rollback.
Usage:
syndicate policy show [--format json|yaml] [--version <v>]
syndicate policy validate <policy-file>
syndicate policy apply <policy-file> [--dry-run]
syndicate policy diff <policy-file>
syndicate policy history [--limit N]
syndicate policy rollback <version>
Examples:
syndicate policy validate ./policy/prod.yaml
syndicate policy apply ./policy/prod.yaml --dry-run
syndicate policy rollback 2026.03.1
syndicate provider
Provider registry operations.
Usage:
syndicate provider list [--class local|approved_hosted|restricted_hosted|blocked] [--output json|table]
syndicate provider show <provider-id>
syndicate provider add [--workspace <path>] [--wire-format openai|anthropic] <url>
syndicate provider register <config-file>
syndicate provider remove <provider-id>
syndicate provider test <provider-id>
syndicate provider capabilities <provider-id>
Examples:
syndicate provider list --output table
syndicate provider test local-ollama
syndicate provider capabilities local-ollama
syndicate audit
Audit-chain query, replay, verification, and export.
Usage:
syndicate audit log [--session <id>] [--since <rfc3339>] [--until <rfc3339>] [--limit <n>] [--event-type <type>] [--actor <identity>] [--output json|ndjson|table]
syndicate audit show <event-id>
syndicate audit replay <session-id> [--stage proposal|canonicalization|policy|approval|execution] [--output json|ndjson]
syndicate audit verify [--cross-session] [--from-export <file>] [--output json|text]
syndicate audit export <session-id> [--out <path>] [--format json|ndjson]
Examples:
syndicate audit verify --cross-session
syndicate audit export 63d5e4f8-17a8-4f62-9568-16f299ec8bc8 --format ndjson --out audit.ndjson
syndicate specialist
Specialist registry management.
Usage:
syndicate specialist list [--status pending|active|suspended|revoked|all] [--output json|table]
syndicate specialist show <specialist-id>
syndicate specialist register <definition-file>
syndicate specialist revoke <specialist-id> --reason "<text>"
syndicate specialist diff <specialist-id> <definition-file>
syndicate specialist history <specialist-id>
Examples:
syndicate specialist list --output table
syndicate specialist register ./specialists/reviewer.yaml
syndicate specialist revoke reviewer.v3 --reason "scope replaced"
syndicate mcp
MCP endpoint registration and validation.
Usage:
syndicate mcp list
syndicate mcp add <name> --url <url> [--transport sse|stdio] [--trust-tier 0|1|2|3] [--capability-declaration <file>]
syndicate mcp remove <name>
syndicate mcp show <name>
syndicate mcp test <name>
Examples:
syndicate mcp add filesystem --url http://localhost:5050 --transport sse --trust-tier 0 --capability-declaration ./mcp/filesystem.yaml
syndicate mcp test filesystem
syndicate permit
Permit inspection and revocation.
Usage:
syndicate permit list [--session <id>] [--status issued|active|consumed|expired|revoked|all] [--output json|table]
syndicate permit show <permit-id>
syndicate permit revoke <permit-id> --reason "<text>"
Examples:
syndicate permit list --session 63d5e4f8-17a8-4f62-9568-16f299ec8bc8
syndicate permit revoke 4dbd41aa-545f-46e0-94a2-46cf782f1d39 --reason "scope changed"
syndicate trust
Trust-boundary management operations.
Usage:
syndicate trust list [--output json|table]
syndicate trust grant <boundary-id> [--reason "<text>"]
syndicate trust revoke <boundary-id> --reason "<text>"
Arguments:
| Argument | Description |
|---|---|
<boundary-id> | Trust boundary identifier. Format varies by boundary type: <specialist-id> for specialist trust, <server-identity>/<tool-name> for MCP tool trust, <path-scope> for path-scope trust |
Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
--output | enum | table | Output format: json, table |
--reason | string | required for revoke | Operator-provided reason for trust change |
Subcommands:
trust list— List all trust boundaries with current tier, confidence score, last-evidence timestamp, and boundary typetrust grant <boundary-id>— Elevate a boundary's trust tier. Emits a trust-grant audit event.trust revoke <boundary-id>— Revoke trust for a boundary, resetting it to untrusted. Immediate effect. The--reasonflag is mandatory. All active permits dependent on the revoked boundary are invalidated.
Examples:
syndicate trust list --output table
syndicate trust grant filesystem/write-file
syndicate trust revoke filesystem/write-file --reason "scope violation detected"
syndicate config
Local operator preferences (separate from policy).
Usage:
syndicate config show
syndicate config set <key> <value>
syndicate config unset <key>
syndicate config init [--workspace <path>]
Examples:
syndicate config set output.format json
syndicate config init --workspace /path/to/repo
syndicate completion
Shell completion generation.
Usage:
syndicate completion bash
syndicate completion zsh
syndicate completion fish
syndicate completion powershell
syndicate version
Version output.
Usage:
syndicate --version
Expected fields: semantic version, commit hash, build timestamp, and release channel (cli_command_reference.md §15.4).
Common exit codes
Consistent exit-code contract across commands:
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General execution error |
| 2 | Denied by policy or approval decision |
| 3 | Interrupted (operator action or timeout) |
| 4 | Governance-suspended mode rejected at session start |
| 5 | Control plane unavailable |
| 6 | Authentication or identity failure |
| 7 | Validation failure |
| 8 | Not found |