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

CommandDescription
fxStart 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 acpStart 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

CommandDescription
fx sessionsList sessions in this workspace. Add --all for every workspace.
fx sessions --liveList only the sessions an fx process has open now, with their subagents. Add --all for every workspace; see See what's running.
fx sessions convertConvert 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.

CommandDescription
fx -cContinue the conversation remembered for this workspace.
fx -rChoose 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

CommandDescription
fx login [vercel|codex|grok]Connect the named account. Omitting the argument selects Vercel.
fx login vercel --api-keySave 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 teamsChoose the Vercel team used by AI Gateway.
fx credits / fx balanceShow the AI Gateway credit balance.
fx modelsList the models of the active provider.
fx permissionsShow 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:

CommandDescription
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 slackSave Slack's server in your profile and sign in to it.
fx mcp listList 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 --allApprove 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

CommandDescription
fx statusShow configuration and runtime information.
fx doctorCheck that fx can work here: settings, credentials, models, MCP servers, sessions, and git. Exits with status 1 when a check fails.
fx doctor --fixAlso remove old terminal and side folders whose session is gone.
fx doctor --deepAlso 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|fishPrint a shell completion script. See Shell completion.
fx helpShow 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.

FlagDescription
--provider <name>Choose a built-in provider or configured connection.
--model <id>Choose a model.
--effort <level>Set reasoning effort.
--fast / --no-fastEnable or disable fast mode.
--ultrafast / --no-ultrafastRequest 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-strictRestrict 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-accessShortcuts 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.

FlagDescription
--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:

FlagDescription
--add-dir <path>Add a directory for this run. Repeat for more directories.
--no-additional-dirsIgnore 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 stauts suggests status, and fx --modle suggests --model.
  • Several unquoted words, such as fx fix the login bug, ask you to quote the prompt.
  • fx -p and fx --print point to fx ask for 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:

ShellFileLine
bash~/.bashrceval "$(fx completion bash)"
zsh~/.zshrc, after compinitsource <(fx completion zsh)
fish~/.config/fish/config.fishfx completion fish | source

Environment overrides

See Configuration for FX_PROVIDER, FX_MODEL, FX_PERMISSION_MODE, and other environment variables.