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 everyflowfield invocation and can also be set through environment variables.
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.Projects
Register and inspect projects, manage guidance files, configure integrations, and control workers.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:
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.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.Inbox
Read and inspect questions that need your attention.Integrations
Connect, check, and disconnect Codex as a coding harness.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.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.
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.Storage
Inspect your workspace and recover from a failed upgrade, all without a running service.--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 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
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.