CLI Reference — cordumctl

Complete command reference for cordumctl, the Cordum control-plane CLI.

For REST API endpoints, see api-reference.md. For pack format details, see pack.md. For configuration, see configuration-reference.md.

Global Flags

Every command accepts these flags. Environment variables are checked when a flag is not provided on the command line.

Flag	Env Variable	Default	Description
`--gateway`	`CORDUM_GATEWAY`	`http://localhost:8081`	Gateway base URL
`--api-key`	`CORDUM_API_KEY`	(none)	API authentication key
`--tenant`	`CORDUM_TENANT_ID`	`default`	Tenant ID
`--cacert`	`CORDUM_TLS_CA`	(none)	CA certificate for TLS verification
`--insecure`	`CORDUM_TLS_INSECURE`	`false`	Skip TLS verification (dev/debug only)

# Flags take precedence over env vars
cordumctl status --gateway https://prod:8081 --api-key $KEY --cacert ./certs/ca/ca.crt

Command Summary

Command	Description
`init`	Scaffold a new Cordum project
`generate-certs`	Generate TLS certificates (CA, server, client)
`up`	Start production stack via Docker Compose
`dev`	Start development stack via Docker Compose
`status`	Show gateway health and version
`job submit`	Submit a job
`job status`	Get job status
`job logs`	Get job result or error
`workflow create`	Create a workflow from JSON
`workflow delete`	Delete a workflow
`run start`	Start a workflow run
`run delete`	Delete a workflow run
`run timeline`	Get run timeline events
`approval job`	Approve or reject a job
`dlq retry`	Retry a dead-letter job
`topic list`	List canonical topic registrations
`topic create`	Register or update a topic
`topic delete`	Delete a topic registration
`worker credential list`	List worker credentials
`worker credential create`	Create or rotate a worker credential
`worker credential revoke`	Revoke a worker credential
`pack create`	Scaffold a new pack
`pack install`	Install a pack
`pack uninstall`	Uninstall a pack
`pack list`	List installed packs
`pack show`	Show pack details
`pack verify`	Run pack policy simulation tests
`edge init`	Scaffold local Edge config (and optional Claude wrapper)
`edge claude`	Launch a governed Claude Code session
`edge doctor`	Run observe-only local Edge diagnostics
`edge managed-settings`	Render/verify enterprise managed-settings payloads

Project Initialization

`init <dir>`

Scaffold a new Cordum project with Docker Compose, config files, and a sample workflow.

Flag	Default	Description
`--force`	`false`	Overwrite existing files

Files created:

<dir>/
├── docker-compose.yml
├── config/
│   ├── pools.yaml
│   ├── timeouts.yaml
│   └── safety.yaml
├── workflows/
│   └── hello.json
└── README.md

Example:

cordumctl init my-project
cd my-project

TLS Certificate Generation

`generate-certs`

Generate a full TLS certificate chain: CA certificate, server certificate (with SANs for all Cordum services), and client certificate.

Flag	Default	Description
`--dir`	`./certs`	Output directory
`--force`	`false`	Overwrite existing certificates
`--days`	`365`	Certificate validity in days

Certificates use EC P-256 keys with PKCS8 encoding.

# Generate into default ./certs directory
cordumctl generate-certs

# Custom output directory
cordumctl generate-certs --dir /path/to/certs

# Regenerate expired certificates
cordumctl generate-certs --force --days 730

Output structure:

certs/
├── ca/
│   ├── ca.crt          # CA certificate
│   └── ca.key          # CA private key
├── server/
│   ├── tls.crt         # Server certificate (SANs: localhost, service names)
│   └── tls.key         # Server private key
└── client/
    ├── tls.crt         # Client certificate
    └── tls.key         # Client private key

cordumctl up and cordumctl dev auto-generate certificates if certs/ca/ca.crt does not exist. Use generate-certs --force to regenerate manually.

For full TLS documentation, see guides/tls-setup.md.

Stack Management

`up`

Start the production Cordum stack. Requires CORDUM_API_KEY (from environment, flag, or .env file).

Flag	Default	Description
`--file`	`docker-compose.yml`	Compose file path
`--build`	`true`	Build images before starting
`--detach`	`true`	Run in background

The command also sets COMPOSE_HTTP_TIMEOUT and DOCKER_CLIENT_TIMEOUT to 1800 seconds if not already set.

export CORDUM_API_KEY="$(openssl rand -hex 32)"
cordumctl up

`dev`

Start the stack in development mode.

Flag	Default	Description
`--file`	`docker-compose.yml`	Compose file path
`--build`	`true`	Build images before starting
`--detach`	`false`	Run in background

cordumctl dev            # foreground with logs
cordumctl dev --detach   # background

`status`

Print gateway health and version information.

cordumctl status
# {"status":"ok","version":"0.12.0",...}

Job Management

`job submit`

Submit a job to a topic. Either --prompt or --input is required.

Flag	Default	Description
`--topic`	(required)	Job topic (e.g. `job.my-pack.echo`)
`--prompt`		Job prompt text
`--input`		Input JSON (file path or inline)
`--idempotency-key`		Deduplication key
`--capability`		Job capability
`--pack-id`		Pack ID
`--labels`		Labels as JSON object
`--risk-tags`		Comma-separated risk tags
`--requires`		Comma-separated requirements
`--org`		Organization/tenant ID
`--actor-id`		Actor ID
`--actor-type`		Actor type (`human` or `service`)
`--json`	`false`	Output full JSON response

# Simple prompt
cordumctl job submit --topic job.hello-pack.echo --prompt "Hello world"

# With input file and labels
cordumctl job submit \
  --topic job.my-pack.process \
  --input ./input.json \
  --labels '{"env":"staging"}' \
  --risk-tags "pii,financial"

# Full JSON output
cordumctl job submit --topic job.hello-pack.echo --prompt "test" --json

`job status <job_id>`

Get the status of a job.

Flag	Default	Description
`--json`	`false`	Output full job JSON instead of just state

cordumctl job status job-abc123
# running

cordumctl job status job-abc123 --json
# {"id":"job-abc123","status":"running",...}

`job logs <job_id>`

Get the result or error message of a completed job.

cordumctl job logs job-abc123
# {"result":"Hello world!"}

Workflow Management

`workflow create --file <file>`

Create a new workflow from a JSON definition file.

Flag	Default	Description
`--file`	(required)	Path to workflow JSON file

cordumctl workflow create --file workflows/my-pipeline.json
# workflow-xyz789

`workflow delete <workflow_id>`

Delete a workflow by ID.

cordumctl workflow delete workflow-xyz789

Run Management

`run start <workflow_id>`

Start a new run of a workflow.

Flag	Default	Description
`--input`		Input JSON file path or inline JSON
`--dry-run`	`false`	Start in simulation mode
`--idempotency-key`		Deduplication key

# Start with input
cordumctl run start workflow-xyz789 --input '{"key":"value"}'

# Dry run
cordumctl run start workflow-xyz789 --dry-run

`run get <run_id>`

Fetch the full run object as JSON (status, step states, and active delay timers when present).

cordumctl run get run-abc123
# {"id":"run-abc123","workflow_id":"workflow-xyz789","status":"RUNNING",...}

`run delete <run_id>`

Delete a workflow run.

cordumctl run delete run-abc123

`run timeline <run_id>`

Get the full timeline/audit trail of a run.

cordumctl run timeline run-abc123
# [{"event":"step_started","step":"step1","at":"2026-01-15T10:00:00Z"},...]

Approvals

`approval job <job_id>`

Approve or reject a job pending approval. Exactly one of --approve or --reject is required.

Flag	Description
`--approve`	Approve the job
`--reject`	Reject the job

cordumctl approval job job-abc123 --approve

`approval repair <job_id>`

Inspect or apply a repair plan for an approval whose lifecycle has drifted (stale policy snapshot, stale request, terminal workflow run, or legacy partial approval). Defaults to a dry-run that prints the repair plan without mutating state.

Flag	Default	Description
`--apply`	`false`	Apply the repair plan (omit for dry-run inspection)
`--note`		Operator note stored with the repair

# Dry-run: inspect the repair plan
cordumctl approval repair job-abc123

# Apply the repair
cordumctl approval repair job-abc123 --apply --note "stale snapshot after publish"

Dead Letter Queue

`dlq retry <job_id>`

Retry a job that ended up in the dead-letter queue.

cordumctl dlq retry job-dead456

Pack Management

Packs bundle topics, schemas, workflows, config overlays, and policy fragments into installable units. See pack.md for the full format specification.

`pack create <pack_id>`

Scaffold a new pack directory with template files.

Flag	Default	Description
`--dir`	`<pack_id>`	Output directory
`--force`	`false`	Overwrite existing files

Pack IDs must match [a-z0-9-]+.

cordumctl pack create my-agent

Files created:

my-agent/
├── pack.yaml                     # Pack manifest
├── README.md
├── schemas/EchoInput.json        # Sample input schema
├── workflows/echo.yaml           # Sample workflow
└── overlays/
    ├── pools.patch.yaml          # Pool config overlay
    ├── timeouts.patch.yaml       # Timeout config overlay
    └── policy.fragment.yaml      # Policy fragment

`pack install <path|url>`

Install a pack from a local directory, .tgz archive, or HTTPS URL.

This registers pack topics in the canonical topic registry after config overlays are applied, so installed packs pass submit-time unknown-topic validation.

Flag	Default	Description
`--dry-run`	`false`	Print planned changes without applying
`--force`	`false`	Skip core version compatibility check
`--upgrade`	`false`	Overwrite existing resources (schemas/workflows)
`--inactive`	`false`	Install without pool mappings

Validation checks:

Pack manifest syntax
Protocol version compatibility
Core version range (unless --force)
Topic/schema/workflow namespacing

# Install from directory
cordumctl pack install ./my-agent

# Install from tarball
cordumctl pack install my-agent-1.0.0.tgz

# Install from URL
cordumctl pack install https://packs.cordum.io/my-agent/1.0.0.tgz

# Dry run
cordumctl pack install ./my-agent --dry-run

# Upgrade existing
cordumctl pack install ./my-agent --upgrade

`pack uninstall <pack_id>`

Remove an installed pack.

This also removes the pack's topic registrations from the canonical topic registry.

Flag	Default	Description
`--purge`	`false`	Also delete pack's workflows and schemas

cordumctl pack uninstall my-agent
cordumctl pack uninstall my-agent --purge

`pack list`

List all installed packs.

cordumctl pack list
# my-agent    1.0.0    ACTIVE
# demo-guard  0.2.1    INACTIVE

`pack show <pack_id>`

Show detailed information about an installed pack (JSON output).

cordumctl pack show my-agent
# {"id":"my-agent","version":"1.0.0","status":"ACTIVE",...}

`pack verify <pack_id>`

Run policy simulation tests defined in the pack manifest.

cordumctl pack verify my-agent
# PASS: test-allow-echo
# PASS: test-deny-dangerous
# 2/2 tests passed

MCP Management

Manage MCP tool-approvals, tool visibility, signing keys, and governed upstream MCP servers.

`mcp pending`

List pending MCP tool-call approvals.

Flag	Default	Description
`--status`	`pending`	Filter by approval status
`--json`	`false`	Print raw JSON

cordumctl mcp pending

`mcp approve <approval_id>` / `mcp reject <approval_id>`

Resolve a pending MCP tool-call approval.

Flag	Description
`--reason`	Reason text stored with the decision

cordumctl mcp approve mcp-appr-123 --reason "reviewed by on-call"
cordumctl mcp reject mcp-appr-123 --reason "destructive tool"

`mcp tools list`

List MCP tools visible to the caller (full admin catalogue, or scoped to an agent).

Flag	Default	Description
`--agent-id`		Scope the listing to an agent identity (empty = full catalogue)
`--filter`		Case-insensitive substring against tool name + description
`--json`	`false`	Print raw JSON instead of the table

cordumctl mcp tools list --agent-id agent-abc --json

`mcp upstream <add|validate|list|get|disable|enable>`

Manage governed upstream MCP servers.

Flag	Default	Description
`--name`		Upstream name (required for `add`/`validate`)
`--transport`	`http`	Transport: `http`, `sse`, or `stdio`
`--endpoint`		Remote MCP endpoint URL (for `http`/`sse` transports)
`--command`		stdio command argv element — repeatable: pass `--command` once per argv element (e.g. `--command npx --command -y --command my-mcp-server`)
`--auth-secret-ref`		Secret reference (e.g. `secret://...`) for upstream authentication
`--risk`	`medium`	Risk metadata: `low`, `medium`, `high`, or `critical`
`--validate-only`	`false`	Validate the upstream definition without persisting (implied by the `validate` subcommand)

# HTTP upstream
cordumctl mcp upstream add --name github --endpoint https://mcp.example.com

# stdio upstream (repeat --command for each argv element)
cordumctl mcp upstream add --name local-fs --transport stdio \
  --command npx --command -y --command @modelcontextprotocol/server-filesystem

cordumctl mcp upstream list
cordumctl mcp upstream disable github
cordumctl mcp upstream enable github

mcp also exposes keygen (signing key generation) and the preview / attach / rollback client-attach lifecycle. Run cordumctl mcp with no subcommand to see the full usage string.

Shadow Agent Detection

Local, observe-only shadow-agent tooling.

`shadow scan`

Run the observe-only local shadow-agent scanner. Disabled by default — a bare cordumctl shadow scan prints shadow scan disabled by default and exits without scanning. Opt in with --enable-shadow-scan or set CORDUM_EDGE_SHADOW_SCAN_ENABLED=true. Findings are emitted as JSONL.

Flag	Default	Description
`--enable-shadow-scan`	`false`	Opt in to active scanning (required unless `CORDUM_EDGE_SHADOW_SCAN_ENABLED` is set)
`--output`	(stdout)	Write JSONL findings to this file instead of stdout
`--tenant`		Override tenant attribution on findings
`--principal`		Override principal attribution on findings

# Opt in via flag, findings to stdout (JSONL)
cordumctl shadow scan --enable-shadow-scan

# Opt in via env, write findings to a file
CORDUM_EDGE_SHADOW_SCAN_ENABLED=true cordumctl shadow scan --output findings.jsonl

`shadow remediate`

Generate offline advisory remediation guidance for a single finding. Reads one finding JSON from --finding-file (or - for stdin). Offline by default — never contacts the gateway and requires no API key.

Flag	Default	Description
`--finding-file`	(required)	Path to a single finding JSON (use `-` to read from stdin)
`--audience`	`both`	Target audience: `dev`, `enterprise`, or `both`
`--json`	`false`	Emit machine-readable JSON instead of human-readable text
`--omit-commands`	`false`	Suppress `command` and `api_request.body` fields in the output

# From a stored finding file
cordumctl shadow remediate --finding-file finding.json

# From stdin (single finding JSON)
cat finding.json | cordumctl shadow remediate --finding-file -

Environment Variables

Complete list of environment variables used by cordumctl and the services started with up/dev.

CLI Variables

Variable	Default	Description
`CORDUM_GATEWAY`	`http://localhost:8081`	Gateway base URL
`CORDUM_API_KEY`	(none)	API authentication key
`CORDUM_TENANT_ID`	`default`	Tenant ID

Docker Compose Variables

These are used by cordumctl up and cordumctl dev:

Variable	Default	Description
`CORDUM_API_KEY`	(required)	API key for all services
`CORDUM_VERSION`	`latest`	Docker image version tag
`CORDUM_TENANT_ID`	`default`	Default tenant ID
`REDIS_PASSWORD`	(required)	Redis password (generate with `openssl rand -hex 32`)
`CORDUM_API_BASE_URL`		Dashboard API base URL
`CORDUM_PRINCIPAL_ID`		Dashboard principal ID
`CORDUM_PRINCIPAL_ROLE`		Dashboard principal role
`COMPOSE_HTTP_TIMEOUT`	`1800`	Docker Compose HTTP timeout (seconds)
`DOCKER_CLIENT_TIMEOUT`	`1800`	Docker client timeout (seconds)

Pack File Limits

Limit	Value
Maximum files per pack	2,048
Maximum file size	32 MB
Maximum uncompressed size	256 MB
Supported formats	Directory or `.tgz` archive

Topic Management

Manage the canonical topic registry used by the gateway, scheduler, and dashboard.

`cordumctl topic list`

List registered topics with pool mapping, schema bindings, registry status, and active worker count.

cordumctl topic list

`cordumctl topic create <name>`

Flag	Default	Description
`--pool`	(required unless `--status disabled`)	Worker pool name
`--input-schema`		Input schema ID
`--output-schema`		Output schema ID
`--pack-id`		Owning pack ID
`--requires`		Comma-separated capability requirements
`--risk-tags`		Comma-separated risk tags
`--status`	`active`	Topic status: `active`, `deprecated`, or `disabled`

cordumctl topic create job.my-pack.process \
  --pool my-pack \
  --input-schema my-pack/ProcessInput \
  --output-schema my-pack/ProcessResult \
  --pack-id my-pack \
  --requires docker,network:egress \
  --risk-tags external-api

# Disabled topics may omit the pool during staged rollout
cordumctl topic create job.my-pack.legacy --status disabled

`cordumctl topic delete <name>`

Delete a topic registration from the canonical registry.

cordumctl topic delete job.my-pack.legacy

Worker Credential Management

Provision worker credentials used by scheduler attestation mode.

`cordumctl worker credential list`

List issued credentials, including allowlists and revocation state.

cordumctl worker credential list

`cordumctl worker credential create --worker-id <worker_id>`

Create a new worker credential or rotate an existing one. The plaintext token is printed once and must be stored immediately.

Flag	Default	Description
`--worker-id`	(required)	Worker identity to provision
`--allowed-pools`		Comma-separated allowed pools
`--allowed-topics`		Comma-separated allowed topics

cordumctl worker credential create \
  --worker-id external-worker-01 \
  --allowed-pools my-pack \
  --allowed-topics job.my-pack.process

`cordumctl worker credential revoke --worker-id <worker_id>`

Revoke an issued worker credential.

cordumctl worker credential revoke --worker-id external-worker-01

Pool Management

Manage worker pools dynamically without restarting services.

`cordumctl pool list`

List all pools with worker counts and utilization.

cordumctl pool list

`cordumctl pool get <name>`

Get detailed pool information as JSON.

cordumctl pool get gpu-batch

`cordumctl pool create <name>`

Create a new worker pool.

Flag	Default	Description
`--requires`		Comma-separated capability requirements
`--description`		Pool description

cordumctl pool create gpu-batch --requires gpu,docker --description "GPU batch pool"

`cordumctl pool update <name>`

Update pool configuration. Only provided flags are changed.

Flag	Default	Description
`--requires`		Comma-separated capability requirements
`--description`		Pool description

cordumctl pool update gpu-batch --description "Updated GPU pool"

`cordumctl pool delete <name>`

Delete a pool. Fails if the pool has active topic mappings unless --force.

Flag	Default	Description
`--force`	false	Force delete even with active topic mappings

cordumctl pool delete gpu-batch --force

`cordumctl pool drain <name>`

Start draining a pool. New jobs stop routing to this pool; in-flight jobs complete normally. The pool auto-transitions to inactive when done.

Flag	Default	Description
`--timeout`	300	Drain timeout in seconds

cordumctl pool drain gpu-batch --timeout 600

`cordumctl pool topic add <pool> <topic>`

Add a topic-to-pool mapping.

cordumctl pool topic add gpu-batch job.ml.train

`cordumctl pool topic remove <pool> <topic>`

Remove a topic-to-pool mapping.

cordumctl pool topic remove gpu-batch job.ml.train

Edge (Compliance Firewall)

cordumctl edge governs AI-agent actions locally. Full flag tables and behavior are documented in the Edge CLI reference.

`edge init`

cordumctl edge init [--cwd path] [--force] [--gateway URL] [--tenant id] \
  [--principal id] [--api-key-env NAME] [--no-wrapper] [--non-interactive]

Scaffold local Edge configuration in the target directory.

`edge claude`

cordumctl edge claude [--policy-mode enforce] [--dry-run|--no-launch] \
  [--settings-output path|-] [--claude-path path] [-- --claude-args]

Launch a governed Claude Code session. Cordum flags go before --; Claude arguments after it.

`edge doctor`

cordumctl edge doctor [--json] [--policy-mode enforce] [--settings-path path] [--claude-path path]

Observe-only diagnostics. Exit 0 = pass/skip, 1 = at least one failure, 2 = warnings only.

`edge managed-settings`

cordumctl edge managed-settings <export|verify|rollback-template> [flags]

Render or verify enterprise managed-settings payloads. See the Edge CLI reference for flags and exit codes.

Service Ports (Default Stack)

Service	Port	Protocol
API Gateway (gRPC)	8080	gRPC
API Gateway (HTTP/REST)	8081	HTTP
API Gateway (metrics)	9092	HTTP
Dashboard	8082	HTTP
Safety Kernel (gRPC)	50051	gRPC
Context Engine (gRPC)	50070	gRPC
Workflow Engine (metrics)	9093	HTTP
NATS	4222	NATS
Redis	6379	Redis

Global Flags​

Command Summary​

Project Initialization​

init <dir>​

TLS Certificate Generation​

generate-certs​

Stack Management​

up​

dev​

status​

Job Management​

job submit​

job status <job_id>​

job logs <job_id>​

Workflow Management​

workflow create --file <file>​

workflow delete <workflow_id>​

Run Management​

run start <workflow_id>​

run get <run_id>​

run delete <run_id>​

run timeline <run_id>​

Approvals​

approval job <job_id>​

approval repair <job_id>​

Dead Letter Queue​

dlq retry <job_id>​

Pack Management​

pack create <pack_id>​

pack install <path|url>​

pack uninstall <pack_id>​

pack list​

pack show <pack_id>​

pack verify <pack_id>​

MCP Management​

mcp pending​

mcp approve <approval_id> / mcp reject <approval_id>​

mcp tools list​

mcp upstream <add|validate|list|get|disable|enable>​

Shadow Agent Detection​

shadow scan​

shadow remediate​

Environment Variables​

CLI Variables​

Docker Compose Variables​

Pack File Limits​

Topic Management​

cordumctl topic list​

cordumctl topic create <name>​

cordumctl topic delete <name>​

Worker Credential Management​

cordumctl worker credential list​

cordumctl worker credential create --worker-id <worker_id>​

cordumctl worker credential revoke --worker-id <worker_id>​

Pool Management​

cordumctl pool list​

cordumctl pool get <name>​

cordumctl pool create <name>​

cordumctl pool update <name>​

cordumctl pool delete <name>​

cordumctl pool drain <name>​

cordumctl pool topic add <pool> <topic>​

cordumctl pool topic remove <pool> <topic>​

Edge (Compliance Firewall)​

edge init​

edge claude​

edge doctor​

edge managed-settings​

Service Ports (Default Stack)​

See Also​