> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowfield.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Flowfield CLI Reference: All Commands, Flags, and Options

> Full flowfield CLI reference covering service, projects, tasks, milestones, inbox, integrations, storage, and updates with global flags and JSON output.

The `flowfield` CLI gives you command-line access to everything in the browser UI — managing projects, tasks, milestones, questions, execution, results, storage, and integrations. Commands inside a registered project directory auto-detect the project from `.flowfield/config.toml`. Use `--project ID` when running from a different directory, and `--help` at any level for options.

## Global options

These flags apply to every `flowfield` invocation and can also be set through environment variables.

| Flag | Default | Environment variable | Description |
| - | - | - | - |
| `--port` | `8765` | `FLOWFIELD_PORT` | Port of the running local service |
| `--data-dir` | `~/.flowfield/` | `FLOWFIELD_DATA_DIR` | Workspace directory for storage and artifacts |
| `--project ID` | auto-detected | — | Project ID; overrides local config auto-detection |
| `--json` | — | — | Emit structured JSON output; errors go to stderr |
| `--version` | — | — | Print the installed version and exit |
| `--help` | — | — | Show options at any command level |

The `FLOWFIELD_UPDATE_CHECKS=0` environment variable disables automatic background update checks when the service starts. Manual checks remain available with `flowfield update check`.

## Service

Start the local service or check the installed version. The service binds to loopback on the configured port and runs in the foreground — stop it with Ctrl-C.

```sh theme={null}
flowfield serve
flowfield serve --port 8770
flowfield --version
flowfield version --json
```

## Projects

Register and inspect projects, manage guidance files, configure integrations, and control workers.

```sh theme={null}
flowfield project init
flowfield project init /absolute/path
flowfield project list
flowfield project show
flowfield project guidance preview
flowfield project guidance install
flowfield project guidance show
flowfield project guidance export --part coordinator
flowfield project guidance remove
flowfield project integration show
flowfield project integration configure --target main --check "make test"
flowfield project workers show
flowfield project workers models
flowfield project workers run
flowfield project workers pause
```

`project init` registers the current directory (or an absolute path you supply) and creates `.flowfield/config.toml`. Three flags let you override derived values at init time:

| Flag | Description |
| - | - |
| `--id` | Explicit project ID |
| `--name` | Display name |
| `--prefix` | Three-letter task prefix (e.g. `APP`) |

The three-letter task prefix is derived from the project name at init and **locks permanently after the first task is created**. Plan your prefix before you start adding tasks.

`project guidance export --part coordinator` prints the packaged coordinator skill without connecting to a running service. `project guidance remove` removes guidance content that Flowfield owns and has not been locally edited, preserving any changes you made.

`project workers run` enables eligible *Up next* starts; `project workers pause` leaves any active workers running but stops new ones from starting. `project workers models` lists the AI models available to choose from.

## Tasks

Inspect tasks, browse activity and revision history, manage execution runs, and review results.

```sh theme={null}
flowfield task list
flowfield task show APP-1
flowfield task activity APP-1
flowfield task relationships APP-1
flowfield task revisions APP-1
flowfield task runs list
flowfield task runs show ATTEMPT_ID
flowfield task runs stop ATTEMPT_ID
flowfield task results list APP-1
flowfield task results show RESULT_ID
flowfield task results review --help
flowfield task results retry-delivery --help
```

Use stable task keys (like `APP-1`) or task IDs to identify tasks. `task runs stop ATTEMPT_ID` targets a single running attempt. Run `task results review --help` for exact-candidate approval and request-changes options — a result revision and candidate commit are required. Run `task results retry-delivery --help` to see recovery options when approved code is blocked from reaching the checkout.

## Milestones

List and inspect milestones that group related tasks.

```sh theme={null}
flowfield milestone list
flowfield milestone --help
```

## Inbox

Read and inspect questions that need your attention.

```sh theme={null}
flowfield inbox list
flowfield inbox show QUESTION_ID
```

Questions preserve their task, attempt, and result bindings. Answering a question does not enable a paused worker queue, and inspecting a result does not approve it.

## Integrations

Connect, check, and disconnect Codex as a coding harness.

```sh theme={null}
flowfield integration connect codex
flowfield integration status codex
flowfield integration disconnect codex
```

All three commands accept these options:

| Option | Description |
| - | - |
| `--port` | Service port (overrides global `--port`) |
| `--name` | Codex MCP connection name (default: `flowfield`) |

`integration connect` sets up the MCP connection and preserves existing harness settings. `integration status` checks configuration and verifies service tools without making a model call. `integration disconnect` removes the connection while retaining all projects and tasks.

## Updates

Check whether a newer version of Flowfield is available.

```sh theme={null}
flowfield update status
flowfield update check
flowfield update status --json
```

`status` reads the service's shared saved result, or the cached result when the service is stopped. `check` requests a manual check from the running service and waits briefly for the result. Both commands accept `--json`; human-readable update notices and errors go to stderr. An unsuccessful manual check exits with an error.

<Note>
  These commands report availability only — they do not install software or start a service. See your package manager (`uv tool upgrade flowfield-core` or `pip install --upgrade flowfield-core`) to actually upgrade.
</Note>

## Storage

Inspect your workspace and recover from a failed upgrade, all without a running service.

```sh theme={null}
flowfield storage status
flowfield storage backups
flowfield storage restore BACKUP_ID --confirm
```

Storage commands run fully offline and accept `--json`. `storage status` and `storage backups` never initialize or modify a database. `storage restore` requires a stopped service and refuses to discard writes made after the snapshot was taken. See the [Storage reference](/reference/storage) for full details on automatic migrations, recovery limits, and full backups.

## JSON output

Add `--json` to most data commands to receive structured output instead of human-formatted text. Errors always go to stderr with a nonzero exit status, whether or not `--json` is set.

Paged reads return cursors and truncation metadata alongside their results. Always follow those cursors rather than treating the first page as the complete history of a task, project, or inbox.

## Automation notes

<Note>
  Versioned edits require the current revision of the record you are editing. If you read a record and then edit it, do not overwrite newer intent that arrived between your read and your write — fetch the current revision first.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.