CLI Reference

The orch8 CLI provides admin operations against a running Orch8 engine. Written in Go, it is distributed via Homebrew and curl. All commands communicate with the engine's REST API so there is no direct database access required.

Installation#

Install the CLI on macOS or Linux using Homebrew, or download the binary directly with curl.

Homebrew (macOS / Linux)#

Bash

brew install orch8-io/orch8/orch8-cli

curl#

Bash

curl -fsSL https://orch8.io/install-cli.sh | sh

Verify#

Bash

orch8 --version
# orch8-cli v0.9.2 (go1.22.4, linux/amd64)

Tip

Run orch8 help at any time to see all available commands, or orch8 <command> --help for detailed usage of a specific command.

Configuration#

By default the CLI connects to http://localhost:8080. Override the endpoint and authentication with environment variables or per-command flags.

Environment variables#

Bash

export ORCH8_API_URL=https://engine.example.com
export ORCH8_API_KEY=your-api-key
export ORCH8_TENANT=acme

Per-command flags#

Flags take precedence over environment variables. This is useful when scripting against multiple environments.

Bash

orch8 --api-url https://engine.example.com \
      --api-key sk-... \
      instances list --tenant acme

Note

The --tenant flag is required for all data commands. Set ORCH8_TENANT to avoid repeating it on every call.

Instance Management#

Instances represent individual workflow executions. Use these commands to list, inspect, signal, and bulk-manage instances.

Listing instances#

Bash

# List instances (shows ID, sequence, state, created_at)
orch8 instances list --tenant acme --state scheduled --limit 50

Example output:

ID                                    SEQUENCE        STATE       CREATED
a1b2c3d4-e5f6-7890-abcd-ef1234567890  onboarding/v2   running     2025-06-01T10:30:00Z
b2c3d4e5-f6a7-8901-bcde-f12345678901  invoice/v1      scheduled   2025-06-01T10:28:12Z
c3d4e5f6-a7b8-9012-cdef-123456789012  onboarding/v2   paused      2025-06-01T09:55:43Z

Getting instance details#

Bash

# Get detailed instance state (shows context, current step, outputs)
orch8 instances get <instance-id>

Returns the full instance payload including context, current step index, step outputs, and checkpoint history.

Sending signals#

Bash

# Pause a running instance
orch8 instances signal <instance-id> pause

# Resume a paused instance
orch8 instances signal <instance-id> resume

# Cancel an instance
orch8 instances signal <instance-id> cancel

# Update instance context with a JSON payload
orch8 instances signal <instance-id> update-context '{"replied": true}'

Bulk operations#

Bash

# Bulk cancel by filter
orch8 instances bulk-cancel --namespace production --state paused

Warning

Bulk operations cannot be undone. Always use the --dry-run flag first to preview which instances will be affected.

Sequence Management#

Sequences define the steps and transitions of a workflow. Use these commands to create, list, inspect, and version-manage sequences.

Creating a sequence#

Bash

# Create a sequence from a JSON file
orch8 sequences create --file ./my-sequence.json --tenant acme

Listing sequences#

Bash

# List all sequences for a tenant
orch8 sequences list --tenant acme

Getting a sequence definition#

Bash

# Get the full definition
orch8 sequences get <sequence-id>

Managing versions#

Bash

# List all versions of a sequence
orch8 sequences versions <sequence-name>

# Deprecate a specific version
orch8 sequences deprecate <sequence-id>

Note

Deprecating a sequence version does not affect running instances. It only prevents new instances from being created with that version.

Cron Management#

Cron schedules allow you to start workflow instances on a recurring basis. The engine evaluates schedules every minute.

Bash

# List cron schedules
orch8 cron list --tenant acme

# Enable a schedule
orch8 cron enable <cron-id>

# Disable a schedule
orch8 cron disable <cron-id>

Checkpoints#

Checkpoints capture the state of an instance at each step boundary. They enable resumption after crashes and provide an audit trail.

Bash

# List checkpoints for an instance
orch8 checkpoints list <instance-id>

# Prune old checkpoints (keep last N)
orch8 checkpoints prune <instance-id> --keep 5

Tip

Pruning checkpoints reclaims storage but removes the ability to replay from those earlier points. Keep at least the last 3 for reliable crash recovery.

Health Checks#

Health endpoints let you verify that the engine and its dependencies are operational. They are designed for use with container orchestrators.

Bash

# Liveness — confirms the process is running
orch8 health live

# Readiness — confirms DB connectivity and migration state
orch8 health ready

# Circuit breaker status
orch8 circuit-breakers list
orch8 circuit-breakers reset <handler-name>

Tip

Use orch8 health ready in Kubernetes readiness probes and orch8 health live for liveness probes. The readiness check verifies database connectivity so traffic is only routed to fully operational pods.

Worker Debugging#

When tasks are stuck or workers are unresponsive, use these commands to inspect the task queue and recover individual tasks.

Listing pending tasks#

Bash

# List pending worker tasks
orch8 workers tasks --state pending --limit 20

Inspecting a task#

Bash

# Check worker task details (payload, attempts, last error)
orch8 workers tasks get <task-id>

Requeuing a stuck task#

Bash

# Requeue a stuck task for immediate retry
orch8 workers tasks requeue <task-id>

Warning

Requeuing a task resets its attempt counter. If the root cause has not been resolved the task will fail again and may hit the retry limit.

Ready to try Orch8?

One command to install. Two minutes to your first workflow.

Bash

curl -fsSL https://orch8.io/start.sh | sh

Quick Start Guide Or skip the setup with Cloud →

Previous← SQLite & Test Mode NextCore Concepts →