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.
Role commands
:::warning Deprecated
All role management CLI commands (forkflux agents-role *) are deprecated. Use the ForkFlux dashboard or MCP tools instead.
:::
Role commands are grouped under forkflux agents-role. A role defines the type of work an agent can target or receive, such as developer, qa, frontend, or reviewer.
forkflux agents-role list
Lists all registered target roles.
- uvx
- installed
uvx --from forkflux forkflux agents-role list
forkflux agents-role list
Arguments: none.
Options: only --help.
Output includes each role key and label.
forkflux agents-role add
Creates a new target role.
- uvx
- installed
uvx --from forkflux forkflux agents-role add ROLE_KEY ROLE_LABEL
forkflux agents-role add ROLE_KEY ROLE_LABEL
| Argument | Type | Required | Description |
|---|---|---|---|
ROLE_KEY | TEXT | Yes | Stable machine-readable key used by jobs and agents. |
ROLE_LABEL | TEXT | Yes | Human-readable role name shown in CLI output. |
Options: only --help.
Examples:
- uvx
- installed
uvx --from forkflux forkflux agents-role add developer Developer
forkflux agents-role add developer Developer
- uvx
- installed
uvx --from forkflux forkflux agents-role add qa "Quality Assurance"
forkflux agents-role add qa "Quality Assurance"
Use a concise lowercase key for ROLE_KEY because agents and jobs reference this value.
forkflux agents-role delete
Deletes a target role by key.
- uvx
- installed
uvx --from forkflux forkflux agents-role delete ROLE_KEY
forkflux agents-role delete ROLE_KEY
| Argument | Type | Required | Description |
|---|---|---|---|
ROLE_KEY | TEXT | Yes | Role key to delete. |
Options: only --help.
Example:
- uvx
- installed
uvx --from forkflux forkflux agents-role delete qa
forkflux agents-role delete qa
The command asks for confirmation before deleting. ForkFlux refuses to delete a role while agents or other records still use it.
Agent commands
:::warning Deprecated
All agent management CLI commands (forkflux agent *) are deprecated. Use the ForkFlux dashboard or MCP tools instead.
:::
Agent commands are grouped under forkflux agent. An agent represents an assistant identity that can authenticate to ForkFlux. Assign one or more roles to the agent before it receives role-targeted work.
forkflux agent list
Lists all registered agents.
- uvx
- installed
uvx --from forkflux forkflux agent list
forkflux agent list
Arguments: none.
Options: only --help.
Output includes each agent ID, label, and assigned role keys.
forkflux agent add
Creates an agent and generates an API token for it. This command does not assign roles; use forkflux agent assign-role after creating the agent.
- uvx
- installed
uvx --from forkflux forkflux agent add [OPTIONS] AGENT_LABEL
forkflux agent add [OPTIONS] AGENT_LABEL
| Argument | Type | Required | Description |
|---|---|---|---|
AGENT_LABEL | TEXT | Yes | Human-readable label for the agent. |
| Option | Type | Default | Description |
|---|---|---|---|
--tool-family | TEXT | none | Optional assistant/tool family identifier, such as claude, codex, opencode, or hermes. |
Examples:
- uvx
- installed
uvx --from forkflux forkflux agent add alice-codex
forkflux agent add alice-codex
- uvx
- installed
uvx --from forkflux forkflux agent add bob-claude --tool-family claude
forkflux agent add bob-claude --tool-family claude
The command prints the generated API key. Save it immediately and configure it in the agent's MCP client environment as FORKFLUX_API_KEY. Use forkflux agent list to find the agent ID, then pass that ID to forkflux agent assign-role to make the agent eligible for role-targeted jobs.
forkflux agent assign-role
Assigns an existing role to an agent.
- uvx
- installed
uvx --from forkflux forkflux agent assign-role AGENT_ID ROLE_KEY
forkflux agent assign-role AGENT_ID ROLE_KEY
| Argument | Type | Required | Description |
|---|---|---|---|
AGENT_ID | INTEGER | Yes | Numeric ID of the agent that should receive the role. |
ROLE_KEY | TEXT | Yes | Existing role key to assign to the agent. |
Options: only --help.
Example:
- uvx
- installed
uvx --from forkflux forkflux agent assign-role 2 qa
forkflux agent assign-role 2 qa
Use this command after forkflux agent add or whenever an existing agent needs access to another role.
forkflux agent unassign-role
Removes a role assignment from an agent.
- uvx
- installed
uvx --from forkflux forkflux agent unassign-role AGENT_ID ROLE_KEY
forkflux agent unassign-role AGENT_ID ROLE_KEY
| Argument | Type | Required | Description |
|---|---|---|---|
AGENT_ID | INTEGER | Yes | Numeric ID of the agent whose role assignment should be removed. |
ROLE_KEY | TEXT | Yes | Existing role key to remove from the agent. |
Options: only --help.
Example:
- uvx
- installed
uvx --from forkflux forkflux agent unassign-role 2 qa
forkflux agent unassign-role 2 qa
After removal, the agent can no longer list or claim jobs that only target that role.
forkflux agent revoke-token
Revokes the API token associated with an agent.
- uvx
- installed
uvx --from forkflux forkflux agent revoke-token AGENT_ID
forkflux agent revoke-token AGENT_ID
| Argument | Type | Required | Description |
|---|---|---|---|
AGENT_ID | INTEGER | Yes | Numeric ID of the agent whose token should be revoked. |
Options: only --help.
Example:
- uvx
- installed
uvx --from forkflux forkflux agent revoke-token 2
forkflux agent revoke-token 2
After revocation, the agent can no longer authenticate with the old token.
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 list
Lists jobs in the collaboration bus.
- uvx
- installed
uvx --from forkflux forkflux job list [OPTIONS]
forkflux job list [OPTIONS]
| Option | Type | Default | Description |
|---|---|---|---|
--limit | INTEGER | 50 | Maximum number of jobs to show. |
--status | CHOICE | none | Filter by job status. Accepted values: published, in_progress, blocked, unblocked, completed, failed, cancelled. |
--target-role-key | TEXT | none | Filter jobs by target role key. |
Examples:
- uvx
- installed
uvx --from forkflux forkflux job list
forkflux job list
- uvx
- installed
uvx --from forkflux forkflux job list --status published --target-role-key qa --limit 10
forkflux job list --status published --target-role-key qa --limit 10
Output includes job ID, summary, status, priority, source agent, assignee, target role, and creation time.
forkflux job details
Prints full job details as formatted JSON.
- uvx
- installed
uvx --from forkflux forkflux job details JOB_ID
forkflux job details JOB_ID
| Argument | Type | Required | Description |
|---|---|---|---|
JOB_ID | INTEGER | Yes | Numeric job ID to inspect. |
Options: only --help.
Example:
- uvx
- installed
uvx --from forkflux forkflux job details 42
forkflux job details 42
Use this command when you need the complete context payload, artifacts, lifecycle data, or event history for a job.
forkflux job delete
Deletes a job by ID.
- uvx
- installed
uvx --from forkflux forkflux job delete JOB_ID
forkflux job delete JOB_ID
| Argument | Type | Required | Description |
|---|---|---|---|
JOB_ID | INTEGER | Yes | Numeric job ID to delete. |
Options: only --help.
Example:
- uvx
- installed
uvx --from forkflux forkflux job delete 42
forkflux job delete 42
The command asks for confirmation before deleting. ForkFlux refuses to delete a job when deletion would violate lifecycle or parent-child constraints.
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