CLI commands

Run fx with no command to start a fresh interactive session. Use the commands below to run requests, continue sessions, inspect local state, and configure fx.

fx <command> --help prints the exact option list for one command. Interactive / commands are documented separately in Slash commands.

These commands accept --json for machine-readable output: ask, status, doctor, permissions, models, workspace, session, sessions, background, usage, credits, and upgrade. The others print text only.

Run fx

Command	Purpose
`fx`	Start a fresh interactive session.
`fx ask <prompt>`	Run one noninteractive request. See `fx ask`.
`fx resume [last\|<id>]`	Continue a saved interactive session; `--id <id>` forces an exact ID.
`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 and fx issue accept --auto to review unresolved permission requests automatically, and must run inside a Git repository.

Sessions and local records

Command	Purpose
`fx sessions`	List sessions for the current workspace. Accepts `--all`, `--limit <1-100>`, and `--cursor <cursor>`.
`fx session <last\|id>`	Inspect one session. `--id <id>` forces an exact ID.
`fx session migrate <id>`	Migrate a saved session to the current format; `--allow-large` permits an oversized session.
`fx session recover <id>`	Copy a recoverable corrupt session without changing the source.
`fx background [last\|<id>]`	List or inspect background commands.
`fx usage [--period <24h\|7d\|30d>]`	Show token usage and spend recorded by fx on this machine.

See Sessions for the full workflow.

Account and configuration

Command	Purpose
`fx login [vercel\|codex\|grok]`	Sign in with Vercel, or with a Codex or Grok subscription.
`fx logout [vercel\|codex\|grok]`	Sign out of the saved session for that provider.
`fx provider <gateway\|codex\|grok>`	Choose the provider fx uses for models.
`fx setup`	Configure an AI Gateway API key.
`fx teams`	Choose the Vercel team used by AI Gateway.
`fx credits` / `fx balance`	Show the AI Gateway credit balance for the active credential. Gateway only.
`fx models`	List the models of the active provider.
`fx permissions`	Show the permission mode and rules.
`fx workspace [list\|add PATH\|remove PATH\|clear]`	Manage additional workspace directories.

fx login, fx logout, fx setup, and fx teams are interactive. Selecting a built-in subscription provider can start sign-in when it has no saved session. See Authentication.

The custom model connections preview also accepts fx provider <configured-name>. Define the connection in your private profile first. This selection does not open a custom-provider login flow; bearer credentials come from the connection's named environment variable. Use FX_PROVIDER=<configured-name> for a process-only selection.

MCP management

Top-level MCP commands operate without opening the interactive shell or contacting AI Gateway:

Command	Purpose
`fx mcp add <name> <command> [args...]`	Add or replace a local stdio server in the private profile.
`fx mcp add --transport http <name> <url>`	Add or replace a Streamable HTTP server in the private profile.
`fx mcp list`	Inspect profile and project configuration plus stored authentication without connecting servers.
`fx mcp list --connect`	Connect configured servers, run discovery, and show live health.
`fx mcp auth <name>`	Run the remote OAuth flow.
`fx mcp logout <name>`	Remove stored credentials and attempt remote revocation when supported.
`fx mcp path`	Print the private profile path.
`fx mcp remove <name>`	Remove a server from the private profile.
`fx mcp trust approve\|reject <name>`	Approve or reject one project server for the current workspace.
`fx mcp trust approve-all`	Approve every server in the current workspace `.mcp.json`.
`fx mcp trust reset`	Clear the current workspace's project MCP choices.

These commands print text rather than structured JSON. See MCP for configuration shapes, interactive commands, and project trust behavior.

Diagnostics and maintenance

Command	Purpose
`fx status`	Show configuration and runtime information.
`fx doctor`	Run local health and preflight checks.
`fx upgrade [--channel <stable\|dev>]`	Upgrade fx and optionally remember a release channel.
`fx help`	Show top-level help. `-h` and `--help` are aliases.

Global flags

Global flags are leading flags: place them before a command.

--full-access disables fx permission checks for the run. --yolo remains a backward-compatible alias. See Permissions before using it.
--context-limit <name=bytes|off> overrides one context limit and can be repeated.
--add-dir <path> adds a process-only workspace directory and can be repeated.
--no-additional-dirs ignores saved additional directories for this process.
--provider <name> overrides the model provider for an interactive session: gateway, codex, grok, or a configured provider name. The saved provider in settings is unchanged.
--model <id> overrides the model for an interactive session.
--effort <level> overrides the reasoning effort for an interactive session.
--fast and --no-fast turn fast mode on or off for an interactive session. See Models.
--provider-order <a,b,...> prefers the listed gateway providers in order; --provider-strict and --no-provider-strict toggle restriction to that list. The same flags work after fx ask for one run. See Gateway provider routing.
-r opens the interactive session picker.
-c, --continue, and --resume-last resume the latest workspace session.
--resume [last|<id>] resumes the latest session when no target is provided, while --resume-<id> resumes an exact session ID.
-h, --help prints help; -v, --version prints the version.

See Additional workspaces and Context limits for the full behavior of those repeatable global flags.

Environment overrides

FX_MODEL, FX_PERMISSION_MODE, FX_MAX_AGENT_STEPS, and the other supported variables are listed in Configuration. They affect only the current process and are never written back to settings.

If a command fails or does not report what you expect, see Troubleshooting.