Documentation

cordumctl CLI Reference

cordumctl is the primary interface for interacting with the Cordum control plane. Manage jobs, workflows, approvals, packs, and DLQ entries from your terminal. Policy, config, and schema operations are available via the REST API.

Installation

Quickstart Script

One-liner that starts a full local stack

./tools/scripts/quickstart.sh

Install Script

Downloads and starts with Docker Compose

curl -fsSL https://raw.githubusercontent.com/cordum-io/cordum/main/tools/scripts/install.sh | bash

Build from Source

Compile the binary with Go

make build SERVICE=cordumctl
# Binary at bin/cordumctl

Go Run

Run without building

go run ./cmd/cordumctl <args>

Verify installation

cordumctl status
# or
cordumctl --help

Global Flags

These flags apply to every command. They can also be set via environment variables.

Flag	Env Var	Default	Description
--gateway	CORDUM_GATEWAY	http://localhost:8081	Gateway base URL
--api-key	CORDUM_API_KEY	—	API key for authentication
--tenant	CORDUM_TENANT_ID	default	Tenant ID for multi-tenancy

Setting globals via environment

export CORDUM_GATEWAY=http://localhost:8081
export CORDUM_API_KEY="$(openssl rand -hex 32)"
export CORDUM_TENANT_ID=default

Setup

Command	Description	Flags
cordumctl init <dir>	Scaffold a new Cordum project	--force
cordumctl up	Start the stack (background)	--file, --build, --detach
cordumctl dev	Start the stack (foreground)	--file, --build
cordumctl status	Check gateway health	—

Jobs

Command	Description	Flags
cordumctl job submit	Submit a job to a topic	--topic, --prompt, --input, --capability, --pack-id, --risk-tags, --requires, --actor-id, --actor-type, --idempotency-key, --json
cordumctl job status <id>	Get job status	--json
cordumctl job logs <id>	Get job result/output	—

Workflows

Command	Description	Flags
cordumctl workflow create	Create a workflow definition	--file
cordumctl workflow delete <id>	Delete a workflow definition	—

Runs

Command	Description	Flags
cordumctl run start <wf_id>	Start a workflow run	--input, --dry-run, --idempotency-key
cordumctl run delete <run_id>	Delete a run	—
cordumctl run timeline <run_id>	Get the append-only run timeline	—

Approvals

Command	Description	Flags
cordumctl approval step <wf> <run> <step>	Approve or reject a workflow step	--approve \| --reject
cordumctl approval job <job_id>	Approve or reject a job	--approve \| --reject

DLQ

Command	Description	Flags
cordumctl dlq list	List DLQ entries	—
cordumctl dlq retry <job_id>	Retry a failed job from the DLQ	—
cordumctl dlq delete <id>	Delete a DLQ entry	—

Packs

Command	Description	Flags
cordumctl pack create <id>	Scaffold a new pack	--dir, --force
cordumctl pack install <path\|url>	Install a pack	--upgrade, --inactive, --dry-run, --force
cordumctl pack uninstall <id>	Uninstall a pack	--purge
cordumctl pack list	List installed packs	—
cordumctl pack show <id>	Show pack details	—
cordumctl pack verify <id>	Run pack policy simulations	—

Job Submission

Submit a job and check result

# Submit with inline input
job_id=$(cordumctl job submit \
  --topic job.hello-pack.echo \
  --input '{"message":"Hello, world!","author":"Alice"}')

echo "Job ID: $job_id"

# Poll status
cordumctl job status $job_id

# Get result when SUCCEEDED
cordumctl job logs $job_id

Submit with file input and metadata

cordumctl job submit \
  --topic job.sre.triage \
  --input incident.json \
  --capability sre.triage \
  --risk-tags "high-risk,data-access" \
  --actor-id alice@example.com \
  --actor-type human \
  --idempotency-key "incident-42" \
  --json

Workflow Lifecycle

Create, run, approve, and inspect a workflow

# Create workflow from file
cordumctl workflow create --file workflows/triage.json

# Start a run
run_id=$(cordumctl run start sre.triage \
  --input '{"alert_id":"alert-99"}')

# List pending approvals and approve
cordumctl approval step sre.triage $run_id review-step --approve

# View the full timeline
cordumctl run timeline $run_id

# Dry-run mode (validates without executing)
cordumctl run start sre.triage --input input.json --dry-run

Policy, Config & Schemas (REST API)

Policy evaluation, simulation, config management, and schema operations are available via the REST API, not the CLI. Use curl or any HTTP client against the API Gateway.

REST API examples

# Simulate a policy change
curl -X POST http://localhost:8081/api/v1/policy/simulate \
  -H "X-API-Key: $CORDUM_API_KEY" \
  -H "X-Tenant-ID: default" \
  -H "Content-Type: application/json" \
  -d '{"topic":"job.deploy.k8s","tenant":"default"}'

# Explain a policy decision
curl -X POST http://localhost:8081/api/v1/policy/explain \
  -H "X-API-Key: $CORDUM_API_KEY" \
  -H "X-Tenant-ID: default" \
  -H "Content-Type: application/json" \
  -d '{"topic":"job.deploy.k8s","capability":"deploy.k8s","tenant":"default"}'

# Get system-scope config (envelope form)
curl "http://localhost:8081/api/v1/config?scope=system&scope_id=default&envelope=true" \
  -H "X-API-Key: $CORDUM_API_KEY" \
  -H "X-Tenant-ID: default"

# Register a schema
curl -X POST http://localhost:8081/api/v1/schemas \
  -H "X-API-Key: $CORDUM_API_KEY" \
  -H "X-Tenant-ID: default" \
  -H "Content-Type: application/json" \
  -d @schema.json

Pack Management

Create, install, verify, and uninstall a pack

# Scaffold a new pack
cordumctl pack create my-pack
cd my-pack
# Edit pack.yaml, add workflows/ and schemas/

# Dry-run installation to preview changes
cordumctl pack install . --dry-run

# Install the pack
cordumctl pack install .

# Verify policy simulations pass
cordumctl pack verify my-pack

# List and inspect
cordumctl pack list
cordumctl pack show my-pack

# Uninstall (preserves workflows/schemas)
cordumctl pack uninstall my-pack

# Uninstall and purge everything
cordumctl pack uninstall my-pack --purge

--dry-run

Preview changes without writing to the cluster

--upgrade

Overwrite existing workflows and schemas

--inactive

Install without pool mappings (activate later)

DLQ & Retry

Inspect and retry failed jobs

# List DLQ entries
cordumctl dlq list

# Retry a specific failed job
cordumctl dlq retry job-abc123

# Delete a DLQ entry
cordumctl dlq delete dlq-entry-456

Common Workflows

Local Setup

1.cordumctl init my-project
2.cd my-project
3.cordumctl up --detach
4.cordumctl status

Submit & Check Job

1.cordumctl job submit --topic job.* --input data.json
2.cordumctl job status <job_id>
3.cordumctl job logs <job_id>

Run a Workflow

1.cordumctl workflow create --file wf.json
2.cordumctl run start <wf_id> --input input.json
3.cordumctl approval step <wf> <run> <step> --approve
4.cordumctl run timeline <run_id>

Policy (REST API)

1.curl -X POST localhost:8081/api/v1/policy/explain -d ...
2.curl -X POST localhost:8081/api/v1/policy/simulate -d @new.yaml
3.curl -X POST localhost:8081/api/v1/policy/publish -d @new.yaml

Install a Pack

1.cordumctl pack install ./my-pack --dry-run
2.cordumctl pack install ./my-pack
3.cordumctl pack verify my-pack

Retry from DLQ

1.cordumctl dlq list
2.cordumctl dlq retry <job_id>
3.cordumctl job status <job_id>

Project Scaffold

cordumctl init creates a ready-to-run project directory with Docker Compose, config files, and a sample workflow.

cordumctl init my-project

my-project/
├── docker-compose.yml    # Full 8-service stack
├── config/
│   ├── pools.yaml        # Worker pool configuration
│   ├── timeouts.yaml     # Timeout settings
│   └── safety.yaml       # Safety/policy rules
├── workflows/
│   └── hello.json        # Sample workflow
└── README.md

Pack Manifest

Packs use a pack.yaml manifest. cordumctl pack create scaffolds this structure.

pack.yaml

apiVersion: cordum.io/v1alpha1
kind: Pack

metadata:
  id: my-pack              # ^[a-z0-9-]+$
  version: 0.1.0
  title: My Pack

compatibility:
  protocolVersion: 1

topics:
  - name: job.my-pack.echo
    capability: my-pack.echo

resources:
  schemas:
    - id: my-pack/Input
      path: schemas/input.json
  workflows:
    - id: my-pack.echo
      path: workflows/echo.yaml

overlays:
  config:
    - name: pools
      scope: system
      key: pools
      strategy: json_merge_patch
      path: overlays/pools.patch.yaml
  policy:
    - name: safety
      strategy: bundle_fragment
      path: overlays/policy.fragment.yaml

tests:
  policySimulations:
    - name: allow_echo
      request:
        topic: job.my-pack.echo
        capability: my-pack.echo
      expectDecision: ALLOW

Pack ID

^[a-z0-9-]+$

Topics

job.<pack_id>.*

Workflows

<pack_id>.<name>

Schemas

<pack_id>/<name>

Pack Install Constraints

2,048

Max files

32 MB

Max single file

256 MB

Max uncompressed