CLI

Command-line interface for queue-based workflow execution.

Installation

bun install

Bundled Binary

The CLI can be compiled into a standalone binary:

bun run build:current  # Build for current platform
bun run build          # Build for all platforms

Runtime Requirement: When using the bundled binary, bun must still be installed on the system for workflow step execution. This is because workflow steps are TypeScript files that need to be transpiled and executed at runtime.

# Example Dockerfile
FROM oven/bun:1.2 AS runner
# bun is available from the base image

Commands

Worker

cf worker start [--mode unified|executor|scheduler] [--concurrency n] [--workflows-dir path]

Submit & Manage

cf submit <workflow> [--input '{}' | --input-file path] [--priority n] [--timeout ms]
cf status <runId>
cf cancel <runId> [--reason text]
cf retry <runId> [--reason text]

Workflows & Runs

cf workflows list
cf runs list [--workflow slug] [--status pending|running|completed|failed] [--all]

Worker Modes

• Unified (default) - All loops in one process
• Executor - Execute steps only (requires separate scheduler)
• Scheduler - Schedule steps only (requires separate executors)

Timeouts

3-tier fallback:

1. Step-level: defineStep({ timeoutMs })
2. Submission-level: --timeout flag
3. System default: 300000ms (5 min)

Stale threshold: --stale-threshold (default 30s) - Detects crashed workers via missing heartbeats

Examples

# Start worker
cf worker start --concurrency 5                    # Terminal 1

# Submit and manage workflows
cf submit my-workflow --input '{}' --timeout 60000 # Terminal 2
cf status <runId>

# Scaled deployment
cf worker start --mode scheduler                   # Terminal 1
cf worker start --mode executor --concurrency 10   # Terminal 2-4 (multiple)