Skip to main content

CLI Reference


Global Flags

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

FlagEnv VariableDefaultDescription
--gatewayCORDUM_GATEWAYhttp://localhost:8081Gateway base URL
--api-keyCORDUM_API_KEY(none)API authentication key
--tenantCORDUM_TENANT_IDdefaultTenant ID
--cacertCORDUM_TLS_CA(none)CA certificate for TLS verification
--insecureCORDUM_TLS_INSECUREfalseSkip 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


Project Initialization

init <dir>

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

FlagDefaultDescription
--forcefalseOverwrite 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


Stack Management

up

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

FlagDefaultDescription
--filedocker-compose.ymlCompose file path
--buildtrueBuild images before starting
--detachtrueRun 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.

FlagDefaultDescription
--filedocker-compose.ymlCompose file path
--buildtrueBuild images before starting
--detachfalseRun 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",...}


Workflow Management

workflow create --file <file>

Create a new workflow from a JSON definition file.

FlagDefaultDescription
--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


Approvals

approval job <job_id>

Approve or reject a job pending approval.

FlagDescription
--approveApprove the job
--rejectReject the job
cordumctl approval job job-abc123 --approve


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.

FlagDefaultDescription
--dir<pack_id>Output directory
--forcefalseOverwrite 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.

FlagDefaultDescription
--dry-runfalsePrint planned changes without applying
--forcefalseSkip core version compatibility check
--upgradefalseOverwrite existing resources (schemas/workflows)
--inactivefalseInstall 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.

FlagDefaultDescription
--purgefalseAlso 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


Pack File Limits

LimitValue
Maximum files per pack2,048
Maximum file size32 MB
Maximum uncompressed size256 MB
Supported formatsDirectory or .tgz archive


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.

FlagDefaultDescription
--worker-id(required)Worker identity to provision
--allowed-poolsComma-separated allowed pools
--allowed-topicsComma-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


Service Ports (Default Stack)

ServicePortProtocol
API Gateway (HTTP)8080HTTP
API Gateway (admin)8081HTTP
API Gateway (metrics)9092HTTP
Dashboard8082HTTP
Safety Kernel (gRPC)50051gRPC
Context Engine (gRPC)50070gRPC
Workflow Engine (metrics)9093HTTP
NATS4222NATS
Redis6379Redis

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.

FlagEnv VariableDefaultDescription
--gatewayCORDUM_GATEWAYhttp://localhost:8081Gateway base URL
--api-keyCORDUM_API_KEY(none)API authentication key
--tenantCORDUM_TENANT_IDdefaultTenant ID
--cacertCORDUM_TLS_CA(none)CA certificate for TLS verification
--insecureCORDUM_TLS_INSECUREfalseSkip 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

CommandDescription
initScaffold a new Cordum project
generate-certsGenerate TLS certificates (CA, server, client)
upStart production stack via Docker Compose
devStart development stack via Docker Compose
statusShow gateway health and version
job submitSubmit a job
job statusGet job status
job logsGet job result or error
workflow createCreate a workflow from JSON
workflow deleteDelete a workflow
run startStart a workflow run
run deleteDelete a workflow run
run timelineGet run timeline events
approval jobApprove or reject a job
dlq retryRetry a dead-letter job
topic listList canonical topic registrations
topic createRegister or update a topic
topic deleteDelete a topic registration
worker credential listList worker credentials
worker credential createCreate or rotate a worker credential
worker credential revokeRevoke a worker credential
pack createScaffold a new pack
pack installInstall a pack
pack uninstallUninstall a pack
pack listList installed packs
pack showShow pack details
pack verifyRun pack policy simulation tests

Project Initialization

init <dir>

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

FlagDefaultDescription
--forcefalseOverwrite 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.

FlagDefaultDescription
--dir./certsOutput directory
--forcefalseOverwrite existing certificates
--days365Certificate 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).

FlagDefaultDescription
--filedocker-compose.ymlCompose file path
--buildtrueBuild images before starting
--detachtrueRun 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.

FlagDefaultDescription
--filedocker-compose.ymlCompose file path
--buildtrueBuild images before starting
--detachfalseRun 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.

FlagDefaultDescription
--topic(required)Job topic (e.g. job.my-pack.echo)
--promptJob prompt text
--inputInput JSON (file path or inline)
--idempotency-keyDeduplication key
--capabilityJob capability
--pack-idPack ID
--labelsLabels as JSON object
--risk-tagsComma-separated risk tags
--requiresComma-separated requirements
--orgOrganization/tenant ID
--actor-idActor ID
--actor-typeActor type (human or service)
--jsonfalseOutput 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.

FlagDefaultDescription
--jsonfalseOutput 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.

FlagDefaultDescription
--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.

FlagDefaultDescription
--inputInput JSON file path or inline JSON
--dry-runfalseStart in simulation mode
--idempotency-keyDeduplication key
# Start with input
cordumctl run start workflow-xyz789 --input '{"key":"value"}'

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

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.

FlagDescription
--approveApprove the job
--rejectReject the job
cordumctl approval job job-abc123 --approve

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.

FlagDefaultDescription
--dir<pack_id>Output directory
--forcefalseOverwrite 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.

FlagDefaultDescription
--dry-runfalsePrint planned changes without applying
--forcefalseSkip core version compatibility check
--upgradefalseOverwrite existing resources (schemas/workflows)
--inactivefalseInstall 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.

FlagDefaultDescription
--purgefalseAlso 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

Environment Variables

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

CLI Variables

VariableDefaultDescription
CORDUM_GATEWAYhttp://localhost:8081Gateway base URL
CORDUM_API_KEY(none)API authentication key
CORDUM_TENANT_IDdefaultTenant ID

Docker Compose Variables

These are used by cordumctl up and cordumctl dev:

VariableDefaultDescription
CORDUM_API_KEY(required)API key for all services
CORDUM_VERSIONlatestDocker image version tag
CORDUM_TENANT_IDdefaultDefault tenant ID
REDIS_PASSWORD(required)Redis password (generate with openssl rand -hex 32)
CORDUM_API_BASE_URLDashboard API base URL
CORDUM_PRINCIPAL_IDDashboard principal ID
CORDUM_PRINCIPAL_ROLEDashboard principal role
COMPOSE_HTTP_TIMEOUT1800Docker Compose HTTP timeout (seconds)
DOCKER_CLIENT_TIMEOUT1800Docker client timeout (seconds)

Pack File Limits

LimitValue
Maximum files per pack2,048
Maximum file size32 MB
Maximum uncompressed size256 MB
Supported formatsDirectory 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>

Register a topic or update an existing registration.

FlagDefaultDescription
--pool(required unless --status disabled)Worker pool name
--input-schemaInput schema ID
--output-schemaOutput schema ID
--pack-idOwning pack ID
--requiresComma-separated capability requirements
--risk-tagsComma-separated risk tags
--statusactiveTopic 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.

FlagDefaultDescription
--worker-id(required)Worker identity to provision
--allowed-poolsComma-separated allowed pools
--allowed-topicsComma-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.

FlagDefaultDescription
--requiresComma-separated capability requirements
--descriptionPool 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.

FlagDefaultDescription
--requiresComma-separated capability requirements
--descriptionPool 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.

FlagDefaultDescription
--forcefalseForce 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.

FlagDefaultDescription
--timeout300Drain 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

Service Ports (Default Stack)

ServicePortProtocol
API Gateway (HTTP)8080HTTP
API Gateway (admin)8081HTTP
API Gateway (metrics)9092HTTP
Dashboard8082HTTP
Safety Kernel (gRPC)50051gRPC
Context Engine (gRPC)50070gRPC
Workflow Engine (metrics)9093HTTP
NATS4222NATS
Redis6379Redis

See Also