Skip to main content
The OpenWorkflow CLI is the primary way to set up your project, run workers, and launch the dashboard. CLI commands read your openworkflow.config.ts automatically, or you can override the path with --config.

​
Installation

​
Commands

​
init

Initialize OpenWorkflow in your project:
This interactive command:
  1. Asks which backend to use (SQLite, PostgreSQL, or both)
  2. Installs required dependencies
  3. Creates openworkflow.config.ts
  4. Creates an example workflow in ./openworkflow/
  5. Adds a worker script to package.json
  6. Updates .gitignore for SQLite (if selected)
  7. Adds OPENWORKFLOW_POSTGRES_URL to .env for PostgreSQL (if selected)

​
worker start

Start a worker to process workflows:
Options:
  • --concurrency <n> - Number of concurrent workflow executions (overrides config)
The worker:
  1. Loads your config file
  2. Discovers workflows in the configured directories
  3. Registers all workflows
  4. Starts polling for work
  5. Handles graceful shutdown on SIGINT/SIGTERM

​
dashboard

Start the web dashboard:
The dashboard starts on http://localhost:3000 by default. To use a custom port:
See Dashboard for details.

​
doctor

Diagnose your OpenWorkflow setup:
This command checks:
  • Config file exists and loads correctly
  • Backend connection works
  • Workflow directories exist
  • Workflow files are discoverable
  • Workflows export valid definitions
  • No duplicate workflow names
Example output:

​
--version

Show the CLI version:

​
--help

Show help for any command:

​
Environment Variables

The CLI loads .env files automatically before reading the config.

​
Exit Codes

​
Graceful Shutdown

When running worker start, the CLI handles shutdown signals:
  • SIGINT (Ctrl+C) - Graceful shutdown
  • SIGTERM - Graceful shutdown
On shutdown, the worker:
  1. Stops accepting new work
  2. Waits for active workflows to complete
  3. Closes the backend connection