Skip to main content
The OpenWorkflow CLI (@openworkflow/cli) is the primary way to set up your project, run workers, and launch the dashboard. The CLI reads your openworkflow.config.ts by default, or you can override the path with --config.

​
Installation

​
Commands

​
init

Initialize OpenWorkflow in a project with an existing package.json:
By default, init is interactive and prompts for a backend, installs dependencies, and creates a config, client, example workflow, and runner. It also adds a worker script and updates .gitignore or .env for the selected backend. Options:
  • --backend <backend> - Select sqlite, postgres, or both. With both, PostgreSQL is used when NODE_ENV=production; otherwise SQLite is used.
  • -y, --yes - Skip prompts. Requires --backend and rejects existing configs.
  • --skip-install - Create files without installing dependencies or changing dependency declarations. Prints the installation commands to run later.
For unattended setup without installing dependencies:

​
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

Check your config, backend connection, and workflows for problems.

​
--version

Show the CLI version:

​
--help

Show help for any command:

​
Environment Variables

The CLI loads .env from the current directory before reading the config. You can pass --env-file <path> to load a different .env file.

​
Telemetry

The CLI sends command names, backend types, CLI/Node.js versions, OS, architecture, and a random installation ID to PostHog by default. It does not send project contents, paths, or error messages. Disable telemetry with --no-telemetry or DO_NOT_TRACK=1 in your shell. Any nonempty CI or OPENWORKFLOW_TELEMETRY_DISABLED also disables it.

​
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