CLI reference
Commands available in the fl0w CLI. Run fl0w help for the subcommand list on your installed version. Install and first run are in the Quickstart; sync behavior is described in How it works. For the TUI's slash commands, see TUI slash commands.
Account and sync
| Command | Description |
|---|---|
fl0w | Start the interactive TUI. Requires sign-in. |
fl0w help / -h / --help | Show commands and flags. |
fl0w login | Sign in through the browser. Model calls go through your fl0w account, so you don't need an API key. |
fl0w logout | Sign out. |
fl0w whoami | Show the signed-in account. |
fl0w sync | Sync config, auth, skills, and user tools with fl0w-work, and push pending session and workflow writes. |
fl0w reauth [server...] | Connect to every MCP server in mcp.json, or only the named ones (fl0w reauth github linear), and run the OAuth browser flow for any that need it. Exits 1 if a server fails to connect. |
MCP servers
fl0w mcp [list]
fl0w mcp add <name> <url> [--header "<Name>: <value>"]... [--client-id <id>] [--client-secret <secret>] [--scope "<scopes>"] [--no-oauth]
fl0w mcp add <name> <command> [--env KEY=VALUE]... [-- <arg>...]
fl0w mcp remove <name>fl0w mcp manages the servers in mcp.json. A target starting with http:// or https:// is a remote server. Anything else is a command run over stdio, with its arguments after --. Listing never shows header or env values.
fl0w mcp add linear https://mcp.linear.app/mcp # remote; OAuth runs on first connect
fl0w mcp add api https://api.remote.com/mcp/ --header "X-Team: eng" # extra HTTP headers
fl0w mcp add fs npx --env DEBUG=1 -- -y @modelcontextprotocol/server-filesystem ~/code # local stdio server
fl0w mcp remove fs| Flag | Description |
|---|---|
--header | HTTP header sent to a remote server. Repeatable. |
--client-id | OAuth client id, for providers without dynamic client registration. Register the redirect URI http://localhost:33418/callback with the provider. |
--client-secret | OAuth client secret, used with --client-id. |
--scope | OAuth scopes to request. |
--no-oauth | Never run OAuth for this server. Can't be combined with the OAuth flags. |
--env | KEY=VALUE environment variable for a stdio server. Repeatable. |
- Running
addon an existing name updates it: new headers, env vars, and OAuth options merge in, and anything you leave out keeps its current value. remove, or changing a server's URL, also clears its stored OAuth tokens.- New servers connect the next time fl0w starts. Run
fl0w reauth <name>to sign in right away. - Flag values such as
--client-secretor anAuthorizationheader end up in your shell history. Editmcp.jsondirectly if you'd rather avoid that.
To skip OAuth discovery, set both authorizationUrl and tokenUrl in the server's oauth block in mcp.json. There's no CLI flag for this. See Adding MCP connectors for the file format and remote UI.
Secrets
fl0w secrets [list]
fl0w secrets add <name> [--domain <site>] [--description "<text>"] [--field <field>]... [--env | --no-env]
fl0w secrets remove <name>Secrets let the agent use credentials without seeing them. They're stored in secrets.json (mode 0600). Values never reach the model and are redacted from tool output. Listing never shows values.
fl0w secrets add github --domain github.com # prompts for username and password
fl0w secrets add openai --field token --env # token for the bash tool
fl0w secrets remove githubadd prompts for each field (by default username and password; passwords aren't echoed). The agent references a field as {"secret": "github.password"}. When updating an existing secret, press Enter to keep a field's current value; options you leave out keep their current setting.
| Flag | Description |
|---|---|
--domain | Site where browser_fill may type the secret (https only, subdomains included). Repeatable. "*" allows any site. Without a domain, the agent can't type the secret in the browser. See Browser use. |
--description | Short description shown when listing secrets. |
--field | Field to prompt for instead of username/password, for example --field token. Repeatable. |
--env / --no-env | Expose (or stop exposing) the fields to the agent's bash tool as FL0W_SECRET_<NAME>_<FIELD>. |
You can also edit secrets.json by hand: each top-level key is a secret name, domains lists allowed sites, and every other string is a field.
{
"github": {
"domains": ["github.com"],
"username": "ada",
"password": "…"
}
}Headless commands
fl0w session and fl0w workflow run the agent without the TUI. This is how fl0w-work drives your cloud computer when you automate sessions on a schedule, webhook, or form. Both require fl0w login. They print JSON lines on stdout; MCP progress and warnings go to stderr. They don't save transcripts. To continue a run, pass the earlier turns back with --messages. Run fl0w capabilities to list the skills, MCP servers, user tools, and AGENTS.md that a session can enable (JSON lines). It works signed out. In the TUI, the same flows use /generate and /workflow.
fl0w session
fl0w session [session-id] [--input "<message>"] [--answers '<json>'] [--capabilities '<json>'] [--models '<json>'] [--messages <path.json>]| Argument / flag | Short | Description |
|---|---|---|
session-id | — | Stable id returned with the result. Omit it to get a new id. |
--input | -i | User message for this turn. Required when --messages is omitted or empty. |
--answers | -a | Answers a pending question: {"<question-id>":{"optionId":"<id>"}} or {"<question-id>":{"customText":"..."}}. Without it, --input answers the question as free text. |
--capabilities | -c | {"skills":[],"mcpServers":[],"userTools":[],"agentsMd":[]}, using names from fl0w capabilities. mcpServers takes server names, for example github, and enables all of that server's tools. Defaults to an empty selection. |
--models | — | Model per phase: any of ROUTER, DISCOVERY, PLAN, and EXECUTE, e.g. {"EXECUTE":"provider/model"}. Phases you leave out keep the session's model; "" uses the default. |
--messages | -m | JSON file with the earlier messages, used when continuing a run. |
fl0w workflow
fl0w workflow <workflow-id> [--input "<extra instructions>"] [--session <session-id>] [--messages <path.json>]The positional argument is the id of a workflow saved on fl0w-work, not a file path. Workflow runs are unattended: the agent can't ask questions, so it states its assumptions and keeps going. A run uses the models and capabilities saved with the workflow and skips straight to the execute phase, so it behaves the same as the session you generated it from.
| Flag | Short | Description |
|---|---|---|
--input | -i | Extra instructions appended to the workflow prompt (for example, a webhook payload). |
--session | -s | Stable id returned with the result. |
--messages | -m | JSON file with the earlier messages, used when continuing a run. |
Output and exit codes
Line type | Meaning |
|---|---|
snapshot | The full transcript so far. Sent first, and again after compaction rewrites history. |
message | One new transcript entry, with its index. |
stream_delta / stream_end | A live preview of assistant text. It isn't part of the transcript. |
phase | The phase that is starting (DISCOVERY, PLAN, EXECUTE), then null when the turn ends. |
usage | Context percent, input tokens, total session tokens, and total session cost. |
mcp_auth_required | An MCP server needs OAuth. The run continues without that server's tools. |
result | The final line: status is ok, error, stopped, or needs_input. |
Exit codes: 0 success, 1 error or stopped, 2 waiting on input (needs_input, with a pendingQuestion in the result).
Environment
Config and data live in FL0W_HOME (default ~/.fl0w): mcp.json, secrets.json, auth.json, skills/, tools/, and workspace/. When you're signed in, the TUI and headless commands reconcile config with fl0w-work at startup. mcp.json, secrets.json (encrypted at rest), preferences.json (your last /configure models and capabilities, the defaults for new sessions), and your MCP OAuth tokens sync with your cloud computer; if two machines change the same file, the newer one wins. fl0w mcp and fl0w secrets sync after each change. Run fl0w sync to sync manual edits right away.