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

1brew install orch8-io/orch8/orch8-cli

curl

Bash

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

Verify

Bash

1orch8 --version
2# orch8 0.7.1

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

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

Per-command flags

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

Bash

1orch8 --api-url https://engine.example.com \
2      --api-key sk-... \
3      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

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

Example output:

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

Getting instance details

Bash

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

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

Sending signals

Bash

1# Pause a running instance
2orch8 instances signal <instance-id> pause
3
4# Resume a paused instance
5orch8 instances signal <instance-id> resume
6
7# Cancel an instance
8orch8 instances signal <instance-id> cancel
9
10# Update instance context with a JSON payload
11orch8 instances signal <instance-id> update-context '{"replied": true}'

Bulk operations

Bash

1# Bulk cancel by filter
2orch8 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

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

Listing sequences

Bash

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

Getting a sequence definition

Bash

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

Managing versions

Bash

1# List all versions of a sequence
2orch8 sequences versions <sequence-name>
3
4# Deprecate a specific version
5orch8 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

1# List cron schedules
2orch8 cron list --tenant acme
3
4# Enable a schedule
5orch8 cron enable <cron-id>
6
7# Disable a schedule
8orch8 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

1# List checkpoints for an instance
2orch8 checkpoints list <instance-id>
3
4# Prune old checkpoints (keep last N)
5orch8 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

1# Liveness — confirms the process is running
2orch8 health live
3
4# Readiness — confirms DB connectivity and migration state
5orch8 health ready
6
7# Circuit breaker status
8orch8 circuit-breakers list
9orch8 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

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

Inspecting a task

Bash

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

Requeuing a stuck task

Bash

1# Requeue a stuck task for immediate retry
2orch8 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. Then run your first local sequence.

Bash

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

Quick Start Guide Or skip the setup with Cloud →

Previous← SQLite & Test Mode NextCore Concepts →

Was this helpful?