CLI
This page explains practical command usage patterns. For exhaustive flags and per-command output schemas, use CLI Reference.
Invocation model
syndicate [global-flags] [command] [subcommand] [args] [flags]
Bare invocation launches the TUI and creates or resumes a session (cli_command_reference.md CLI-001, §4).
Global flags
| Flag | Type | Purpose |
|---|---|---|
--workspace <path> | string | Set workspace root |
--config <path> | string | Override config file path |
--session <id> | string | Scope command to a session |
--output <format> | enum | Select output format (text, json, ndjson, table) |
--verbose | bool | Emit more diagnostics |
--quiet | bool | Reduce informational output |
--no-color | bool | Disable colored text output |
--no-tui | bool | Force non-interactive mode |
Source: cli_command_reference.md §3.4.
Primary command patterns
syndicate
Use for interactive governed execution in the TUI.
syndicate
syndicate --session <id>
syndicate run
Use for headless execution and CI pipelines.
syndicate run <workflow-name> --objective "<text>"
syndicate run <workflow-name> --no-tui --output json --objective "<text>"
syndicate approve
Use when approvals are handled outside the TUI.
syndicate approve list --status pending
syndicate approve grant <proposal-id> --reason "<text>"
syndicate session
Use for session inspection, export, attach, and termination.
syndicate session list
syndicate session inspect <session-id>
syndicate policy
Use for policy validation, apply, and rollback operations.
syndicate policy validate <bundle-path>
syndicate policy apply <bundle-path> --dry-run
syndicate provider
Use for provider registration, probing, and capability review.
syndicate provider list
syndicate provider test <provider-id>
syndicate audit
Use for audit-chain verification and evidence export.
syndicate audit verify <session-id>
syndicate audit export <session-id> --format ndjson --out <path>
syndicate specialist
Use for specialist registration and lifecycle control.
syndicate specialist list
syndicate specialist register <definition-file>
syndicate mcp
Use for MCP endpoint registration and inspection.
syndicate mcp list
syndicate mcp add <name> --url <url>
syndicate permit
Use for permit inspection and revocation.
syndicate permit list
syndicate permit revoke <permit-id> --reason "<text>"
syndicate config
Use for local operator preferences (separate from policy).
syndicate config show
syndicate config set <key> <value>
syndicate completion
Use for shell completion script generation.
syndicate completion bash
syndicate completion zsh
Non-interactive and CI usage
--no-tui enforces non-interactive operation and is required for CI/headless flows.
# Governed workflow in CI
syndicate run --no-tui --objective "run tests and verify audit chain" --output json
# Dry run: stages 1-3 only, no permit issuance, no state mutation
syndicate run --no-tui --dry-run --objective "<text>"
# Audit-chain verification in CI
syndicate audit verify --output json
Headless checkpoint behavior: mandatory checkpoints that require operator approval are denied in --no-tui mode. The command exits with code 2 and emits a structured denial record (cli_command_reference.md §6.1, operator_interface_spec.md OI-008).
Dry run behavior
--dry-run executes governed execution stages 1-3 only:
- proposal intake
- canonicalization
- policy evaluation
It does not issue permits and does not mutate state (cli_command_reference.md CLI-005, §6.1).
syndicate run <workflow-name> --dry-run --objective "refactor internal/db/store.go"
Dry-run exit behavior:
- code
0: would be allowed - code
4: would be denied
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Execution error |
| 2 | Denied (policy or approval denial) |
| 3 | Interrupted (operator or timeout) |
| 4 | Dry run would be denied |
| 5 | Control plane unavailable |
Source: cli_command_reference.md §6.3.