# 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](/docs/quickstart); sync behavior is described in [How it works](/docs/how-it-works). For the TUI's slash commands, see [TUI slash commands](/docs/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

```bash
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.

```bash
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 `add` on 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-secret` or an `Authorization` header end up in your shell history. Edit `mcp.json` directly 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](/docs/guides/mcp-connectors) for the file format and remote UI.

## Secrets

```bash
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.

```bash
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 github
```

`add` 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](/docs/guides/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.

```json
{
  "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](/docs/guides/automating-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`](/docs/slash-commands) and [`/workflow`](/docs/slash-commands).

### `fl0w session`

```bash
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`

```bash
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.