CLI commands
Run fx to start an interactive session, or fx "<prompt>" to start one with a first prompt. Use fx <command> --help for command options, or see Slash commands for commands inside fx.
Add --json after the command for machine-readable output with ask, status, doctor, permissions, models, workspace, config, session, sessions, usage, credits, upgrade, slack, mcp list, and mcp show.
Run fx
| Command | Description |
|---|---|
fx | Start a fresh interactive session. |
fx "<prompt>" | Start an interactive session and send the prompt as the first message. Quote the prompt so the shell passes it as one argument. |
fx ask <prompt> | Run one noninteractive request. See fx ask. |
fx pr [context] | Draft a pull request; add --create to publish with gh. |
fx issue [context] | Draft an issue; add --create to publish with gh. |
fx acp | Start an ACP server over stdio. See ACP server. |
fx pr requires a Git repository. Use --create to publish through an authenticated GitHub CLI (gh), or omit it to print the draft. Both commands take the same model and permission flags as fx ask, such as fx pr --model <id> --auto. A flag they don't take is an error, so context that starts with a dash goes after --.
Sessions and local records
| Command | Description |
|---|---|
fx sessions | List sessions in this workspace. Add --all for every workspace. |
fx sessions --live | List only the sessions an fx process has open now, with their subagents. Add --all for every workspace; see See what's running. |
fx sessions convert | Convert every session saved by an earlier fx version. Add --json for the conversion report; see Sessions from earlier versions. |
fx session <last|id> | Inspect one session. --id <id> forces an exact ID, <id>/<agent> reads one of its subagents by name, and --tail <1-1000> shows only the last turns. |
fx session recover <id> | Copy a recoverable corrupt session without changing the source. |
fx usage [--period <today|7d|month>] | Show your provider's usage and spend. Add --json for structured output. |
Use --limit <1-100> and --cursor <cursor> to paginate fx sessions. fx sessions --live doesn't take them, since it lists every live session at once.
| Command | Description |
|---|---|
fx -c | Continue the conversation remembered for this workspace. |
fx -r | Choose a saved conversation. |
fx -r last / fx -r <id> | Resume the latest workspace session or a session by ID. |
fx session resume [last|<id>] | Resume the latest workspace session or a session by ID. |
Add a quoted prompt to send it as the first message after resuming: fx -c "<prompt>" or fx -r <id> "<prompt>".
See Sessions for resuming and recovery.
Account and configuration
| Command | Description |
|---|---|
fx login [vercel|codex|grok] | Connect the named account. Omitting the argument selects Vercel. |
fx login vercel --api-key | Save an AI Gateway API key instead of signing in through the browser. Replaces fx setup, which works with a warning until fx 0.0.18. |
fx logout [vercel|codex|grok] | Sign out of the named account. Omitting the argument selects Vercel. |
fx provider <name> | Choose a built-in provider or configured model connection. |
fx teams | Choose the Vercel team used by AI Gateway. |
fx credits / fx balance | Show the AI Gateway credit balance. |
fx models | List the models of the active provider. |
fx permissions | Show the permission mode and rules. |
fx config [list|get <key>] | Show the values set in the settings files. Add --show-origin to see where each one is set, --global or --workspace to read only the profile's global settings or this workspace's entry, or --json for scripts. |
fx config schema [--project] | Print the JSON Schema for ~/.fx/settings.json, or with --project for .fx.json. See Check settings in your editor. |
fx config set <key> <value> / fx config unset <key> | Save or remove a preference in ~/.fx/settings.json, such as fx config set fast_mode on. |
fx workspace [list|add PATH|remove PATH|clear] | Manage additional workspace directories. |
fx slack <install|status|refresh> | Manage the workspace Slack bot's credentials on this computer. install authorizes the bot through fx.sh and saves its credentials in ~/.fx/slack/installation.json, status shows the saved installation, and refresh renews its tokens without the browser. This is separate from Slack's MCP server, which fx mcp add slack sets up. |
Selecting Codex, Grok, or Gateway with fx provider can start sign-in when credentials are missing. See Authentication.
MCP management
Manage MCP servers from your terminal without starting a model request:
| Command | Description |
|---|---|
fx mcp add <name> <url> | Save a remote server in your profile. If it asks for a login, fx opens your browser and waits for the sign-in; without a browser, it prints the fx mcp login command to run. Add --no-login to save the server without contacting it. |
fx mcp add <name> -- <command> [args...] | Save a local server in your profile. |
fx mcp add slack | Save Slack's server in your profile and sign in to it. |
fx mcp list | List servers, the file that defines each one, and their status, without connecting. |
fx mcp show <name> | Connect to a server and show its status, version, and tools. |
fx mcp login <name> | Sign in to a remote server through your browser. |
fx mcp login --no-browser <name> | Print the sign-in address and take the returned address pasted back. |
fx mcp logout <name> | Sign out, revoking the login where the server supports it. |
fx mcp remove <name> | Remove a server and its saved login. |
fx mcp approve <name> | Approve a project server for the current workspace. |
fx mcp approve --all | Approve every server now in the current workspace's .mcp.json. A server added later still waits for approval. |
fx mcp reject <name> | Reject a project server for the current workspace. |
fx mcp call <tool> [<json>] | Run an MCP tool from a command fx's shell tool runs, and print only its data. Pass - instead of <json> to read the arguments from standard input. |
fx mcp call list <server> | From such a command, list a server's MCP tools, one per line. |
fx mcp call search <query> | From such a command, list the MCP tools that best match a query. |
fx mcp call help <tool> | From such a command, print an MCP tool's description and arguments. |
add takes --header KEY=VALUE for a remote server and --env KEY=VALUE for a local one; repeat either flag for more values. Add --project to add or remove to use the project's .mcp.json, and --json to list or show for machine-readable output; with --json, a usage mistake is reported as JSON too. add and remove don't change a config file that's a link; they name what it points to, so you can edit that file instead. Commands exit 0 on success, 1 on failure, and 2 for a usage mistake; show exits 1 when the server isn't ready. call has more exit codes; see Large results in shell commands.
See MCP for setup, authentication, and project configuration.
Diagnostics and maintenance
| Command | Description |
|---|---|
fx status | Show configuration and runtime information. |
fx doctor | Check that fx can work here: settings, credentials, models, MCP servers, sessions, and git. Exits with status 1 when a check fails. |
fx doctor --fix | Also remove old terminal and side folders whose session is gone. |
fx doctor --deep | Also read every saved file of each session it checks, with no time limit. |
fx upgrade [--channel <stable|dev>] | Upgrade fx and optionally remember a release channel. fx update is an alias. |
fx completion bash|zsh|fish | Print a shell completion script. See Shell completion. |
fx help | Show top-level help. -h and --help are aliases. |
Launch options
Model and routing
These options apply when starting or resuming an interactive session. Put them before or after a first prompt, as in fx --model <id> "<prompt>", and before or after -c, -r, or fx session resume and the session they resume, as in fx -c --model <id> or fx -r <id> --fast.
| Flag | Description |
|---|---|
--provider <name> | Choose a built-in provider or configured connection. |
--model <id> | Choose a model. |
--effort <level> | Set reasoning effort. |
--fast / --no-fast | Enable or disable fast mode. |
--ultrafast / --no-ultrafast | Request or disable the higher-priced Ultrafast tier for an eligible AI Gateway model. Process-only; also supported after ask or acp. |
--provider-order <a,b> | Prefer these AI Gateway providers in order. |
--provider-strict / --no-provider-strict | Restrict routing to that list or allow fallback. |
--permission-mode <ask|auto|full-access> | Set the permission mode for this session without saving it. |
--ask / --auto / --full-access | Shortcuts for each permission mode. --yolo means --full-access. |
fx ask, fx pr, fx issue, and fx acp take the same options after the command, such as fx ask --model <id> "your prompt". fx acp leaves out the two provider-routing flags. See fx ask for its options, including --auto and --full-access.
Placed on the wrong side of a command, these flags fail with a message that says where they go:
$ fx --model <id> ask "your prompt"
fx: put agent-run flags after the command, as in fx ask --model <id>
Agents and instances
These options apply to interactive sessions, including resumed ones, and go in the same places as the model and routing flags, as in fx -c --profile <name>. Before ask, pr, issue, or acp, they're an error.
| Flag | Description |
|---|---|
--profile <name> | Run the session in an agent profile. |
--instances <n> | Start n instances, each with its own conversation. |
Workspace and context
Place these flags before the command. When you start or resume an interactive session, they go in the same places as the model and routing flags:
| Flag | Description |
|---|---|
--add-dir <path> | Add a directory for this run. Repeat for more directories. |
--no-additional-dirs | Ignore saved additional directories for this run. |
--context-limit <name=bytes|off> | Override a context limit. Repeat for more limits. |
--tool-placement <tool=toolbox|direct> | Move a built-in tool into or out of toolbox for this run. Repeat for more tools. |
These flags work with interactive sessions, ask, pr, issue, and acp. See Additional workspaces and Context limits.
Session and help aliases
--continue is equivalent to -c, and -r is short for --resume. With no value, -r or --resume opens the session picker; last resumes the latest workspace session, and an ID resumes that session. --resume=<id> also works. The older spellings --resume-last, --resume-<id>, and fx resume were removed. Use fx --resume last, fx --resume <id>, or fx session resume [last|<id>] instead; each old spelling's error names its replacement.
Use -h or --help for help, and -v or --version for the installed version.
Flags and errors
Flags accept --flag value or --flag=value. When a flag repeats or conflicts with another, the last one wins, so fx --fast --no-fast runs with Fast mode off.
When fx can't use the command line, it exits with status 2 and says what's wrong:
- A typo gets the closest match:
fx stautssuggestsstatus, andfx --modlesuggests--model. - Several unquoted words, such as
fx fix the login bug, ask you to quote the prompt. fx -pandfx --printpoint tofx askfor a one-shot request.
Other failures exit with status 1.
Shell completion
fx completion <shell> prints a completion script for bash, zsh, or fish. Tab then completes commands, subcommands, flags, setting keys after fx config get, set, and unset, and fixed values such as --permission-mode ask|auto|full-access. The script comes from the fx that prints it, so it matches the installed version, and it never runs fx while you type.
To load it in every new shell, add one line to your shell's startup file:
| Shell | File | Line |
|---|---|---|
| bash | ~/.bashrc | eval "$(fx completion bash)" |
| zsh | ~/.zshrc, after compinit | source <(fx completion zsh) |
| fish | ~/.config/fish/config.fish | fx completion fish | source |
Environment overrides
See Configuration for FX_PROVIDER, FX_MODEL, FX_PERMISSION_MODE, and other environment variables.