CLI
The ForkFlux CLI manages the API server, database migrations, roles, agents, API tokens, and jobs.
Use this page as a command reference when you need to operate ForkFlux manually. If you want the shortest path to a working demo, start with the Quickstart guide.
Running the CLI
Run the CLI without installing it into your current Python environment:
uvx --from forkflux forkflux --help
You can also install forkflux via pip into an environment and run:
forkflux --help
Server and setup commands
forkflux serve
Runs database migrations, then starts the ForkFlux API server.
- uvx
- installed
uvx --from forkflux forkflux serve [OPTIONS]
forkflux serve [OPTIONS]
| Option | Type | Default | Description |
|---|---|---|---|
--host | TEXT | 0.0.0.0 | Host interface for the API server to bind to. |
--port | INTEGER | 8000 | Port for the API server to listen on. |
Examples:
- uvx
- installed
uvx --from forkflux forkflux serve
forkflux serve
- uvx
- installed
uvx --from forkflux forkflux serve --host 127.0.0.1 --port 9000
forkflux serve --host 127.0.0.1 --port 9000
Use this command when you want to run the API locally. MCP clients typically connect to the API base URL ending in /api/v1, for example http://127.0.0.1:8000/api/v1.
forkflux init
Initializes the database by applying migrations.
- uvx
- installed
uvx --from forkflux forkflux init
forkflux init
Arguments: none.
Options: only --help.
Use this command before manually creating roles or agents when you do not want to start the API server yet.
SQLite database storage
When no DATABASE_URL environment variable or .env entry is set, ForkFlux uses SQLite with automatic path resolution:
| Priority | Path | Description |
|---|---|---|
| 1 | ./.forkflux/forkflux.db | Local database in the current working directory. |
| 2 | Global data directory | Platform-specific path (e.g. ~/Library/Application Support/forkflux/forkflux.db on macOS). |
forkflux serve and forkflux init auto-detect the database: if a local database exists it is used, otherwise the global path is checked. If neither exists, a new database is created at the local path.
forkflux quickstart --scope influences database resolution when no explicit DATABASE_URL is set, but it does not unconditionally force a specific path for the user scope:
| Scope | Database path |
|---|---|
local (default) / project | ./.forkflux/forkflux.db |
user | Auto-detected: local path if it exists, otherwise global path if it exists, otherwise local path for a fresh install. |
For local and project scopes the database is always created at the local path. For user scope the same auto-detection logic as serve and init applies (see above), so a fresh user-scope install creates the database at the local path, not the global path.
To use PostgreSQL or a custom SQLite path, set the DATABASE_URL environment variable. The scope option does not override an explicit DATABASE_URL.
forkflux quickstart
Initializes a demo environment with database migrations, example roles, example agents, workflow helpers, and MCP server registrations for supported local assistant CLIs.
- uvx
- installed
uvx --from forkflux forkflux quickstart [OPTIONS]
forkflux quickstart [OPTIONS]
Arguments: none.
| Option | Type | Default | Description |
|---|---|---|---|
--scope / -s | CHOICE | local | Configuration scope for MCP server registrations and skill installations. Accepted values: local, project, user. |
The --scope flag controls where the MCP server registration is stored, where workflow skills are installed, and influences SQLite database resolution (when no explicit DATABASE_URL is set):
| Scope | MCP server config | Skills installation path | Database path |
|---|---|---|---|
local | Current working directory only (private, not shared). | Current directory (e.g. .agents/skills, .claude/skills). | ./.forkflux/forkflux.db |
project | Project-level config, shared with repository collaborators. | Current directory (e.g. .agents/skills, .claude/skills). | ./.forkflux/forkflux.db |
user | User-level global config, available across all projects. | Home directory (e.g. ~/.agents/skills, ~/.claude/skills). | Auto-detected: local path if it exists, otherwise global path if it exists, otherwise local path for a fresh install. |
Hermes does not support scoped skill installation. When Hermes is detected, skills are always installed to Hermes's default location regardless of the --scope value. The scope still applies to MCP server config and database path resolution for Hermes as shown above.
Examples:
- uvx
- installed
uvx --from forkflux forkflux quickstart
forkflux quickstart
- uvx
- installed
uvx --from forkflux forkflux quickstart --scope user
forkflux quickstart --scope user
- uvx
- installed
uvx --from forkflux forkflux quickstart -s project
forkflux quickstart -s project
The command checks for supported assistant CLIs: Codex, Claude Code, OpenCode, and Hermes. At least two supported CLIs must be installed for the automated demo setup.
The quickstart flow creates:
| Resource | Value |
|---|---|
| Role | developer / Developer |
| Role | qa / QA |
| Agent | agent-1 with role developer |
| Agent | agent-2 with role qa |
forkflux quickstart modifies local assistant CLI configuration and installs ForkFlux workflow helpers for supported tools. Use it for local demos and evaluation, not production setup.
forkflux stats
:::warning Deprecated
This command is deprecated. Use the ForkFlux dashboard or MCP tools instead.
:::
Shows a handoff metrics snapshot for a configurable time window.
Use this command to quickly assess delivery health, queue pressure, and latency trends without querying the database directly.
- uvx
- installed
uvx --from forkflux forkflux stats [OPTIONS]
forkflux stats [OPTIONS]
Arguments: none.
| Option | Type | Default | Description |
|---|---|---|---|
--window-hours | INTEGER | 24 | Metrics lookback window in hours. Must be at least 1. |
--stuck-minutes | INTEGER | 60 | Threshold (minutes) used to classify active jobs as stuck. Must be at least 1. |
--verbose | FLAG | False | Shows legacy all-time status counters in an additional table. |
Examples:
- uvx
- installed
uvx --from forkflux forkflux stats
forkflux stats
- uvx
- installed
uvx --from forkflux forkflux stats --window-hours 72 --stuck-minutes 30 --verbose
forkflux stats --window-hours 72 --stuck-minutes 30 --verbose
The command prints rich tables with the following sections:
| Section | What it shows |
|---|---|
Pipeline Health | Total jobs in the window, completion rate, failure rate, blocked rate, and number of active agents. |
Workflow Impact | Total handoffs and estimated cumulative time saved. |
Latency (p50 / p90) | Median and tail latencies for time-to-claim and time-to-resolution. |
Active Queue Snapshot | Current counts for published, in_progress, and blocked, plus stuck-job count. |
Historical (All-time Status Counters) | Added only with --verbose; total counters by job status across all time. |
Operator notes:
- The
Published (waiting)row appends a bottleneck hint when one role dominates waiting jobs. - High stuck-job counts usually indicate assignment imbalance, blocked dependencies, or missing agent capacity.
Job commands
:::warning Deprecated
All job management CLI commands (forkflux job *) are deprecated. Use the ForkFlux dashboard or MCP tools instead.
:::
Job commands are grouped under forkflux job. A job is a structured handoff record with a lifecycle status, target role, context payload, and optional artifacts.
forkflux job change-status
Changes a job's lifecycle status on behalf of an agent.
- uvx
- installed
uvx --from forkflux forkflux job change-status [OPTIONS] JOB_ID STATUS AGENT_ID
forkflux job change-status [OPTIONS] JOB_ID STATUS AGENT_ID
| Argument | Type | Required | Description |
|---|---|---|---|
JOB_ID | INTEGER | Yes | Numeric job ID to update. |
STATUS | CHOICE | Yes | New status. Accepted values: published, in_progress, blocked, unblocked, completed, failed, cancelled. |
AGENT_ID | INTEGER | Yes | Numeric ID of the agent performing the status change. |
| Option | Type | Default | Description |
|---|---|---|---|
--failure-reason | TEXT | none | Optional explanation for failed work. |
--blocked-reason | TEXT | none | Optional explanation for blocked work. |
--unblock-reason | TEXT | none | Optional explanation for unblocked work. |
Examples:
- uvx
- installed
uvx --from forkflux forkflux job change-status 42 in_progress 2
forkflux job change-status 42 in_progress 2
- uvx
- installed
uvx --from forkflux forkflux job change-status 42 completed 2
forkflux job change-status 42 completed 2
- uvx
- installed
uvx --from forkflux forkflux job change-status 42 failed 2 --failure-reason "Acceptance tests are blocked by missing credentials."
forkflux job change-status 42 failed 2 --failure-reason "Acceptance tests are blocked by missing credentials."
Use lifecycle statuses according to the intended outcome:
| Status | Use when |
|---|---|
completed | The receiving agent completed the work and met the acceptance criteria. |
failed | The receiving agent cannot complete the work because of an unrecoverable issue. |
cancelled | The user or workflow explicitly abandoned the work. |
blocked | The receiving agent cannot proceed temporarily due to an external dependency or environment issue. Use --blocked-reason to explain the blocker. |
unblocked | The blocker has been resolved. Use --unblock-reason to explain what changed, then transition back to in_progress to resume execution. |
Manual setup example
The role, agent, and job management commands referenced in this example are deprecated. Initialize the database with forkflux init, then create roles, agents, and tokens through the ForkFlux dashboard UI or MCP tools instead.
This sequence initializes ForkFlux and starts the API server:
- uvx
- installed
uvx --from forkflux forkflux init
uvx --from forkflux forkflux serve
forkflux init
forkflux serve