CLI commands
Run fx to start an interactive session. 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, session, sessions, usage, credits, and upgrade.
Run fx
| Command | Description |
|---|---|
fx | Start a fresh interactive session. |
fx ask <prompt> | Run one noninteractive request. See fx ask. |
fx resume [last|<id>] | Resume the latest workspace session or a session by 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 require a Git repository. Use --create to publish through an authenticated GitHub CLI (gh), or omit it to print the draft.
Sessions and local records
| Command | Description |
|---|---|
fx sessions | List sessions in this workspace. Add --all for every workspace. |
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 usage [--period <24h|7d|30d>] | Show token usage and spend recorded by fx on this machine. |
Use --limit <1-100> and --cursor <cursor> to paginate fx sessions.
| Command | Description |
|---|---|
fx -c | Continue the conversation remembered for this workspace. |
fx -r | Choose a saved conversation. |
fx session resume [last|<id>] | Resume the latest workspace session or a session by ID. fx resume is equivalent. |
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 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 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. |
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. |
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> <command> [args...] | Save a local server in your profile. |
fx mcp add --transport http <name> <url> | Save a remote HTTP server in your profile. |
fx mcp list | Show configuration and saved authentication without connecting. |
fx mcp list --connect | Connect servers and check their status. |
fx mcp auth <name> | Sign in to a remote server through your browser. |
fx mcp logout <name> | Sign out of a server. |
fx mcp path | Show the profile path. |
fx mcp remove <name> | Remove a server from your 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 project server approvals and rejections. |
See MCP for setup, authentication, and project configuration.
Diagnostics and maintenance
| Command | Description |
|---|---|
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. |
Launch options
Model and routing
These options apply when starting or resuming an interactive session. Put them before resume when combining them with that command.
| 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. |
--provider-order <a,b> | Prefer these AI Gateway providers in order. |
--provider-strict / --no-provider-strict | Restrict routing to that list or allow fallback. |
For a noninteractive request, put supported options after ask, such as fx ask --model <id> "your prompt". See fx ask for its options, including --auto and --full-access.
Workspace and context
Place these flags before the command, or use them with fx alone:
| 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. |
Directory 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. --resume and --resume-last resume the latest workspace session; --resume <id> or --resume-<id> resumes an exact ID.
Use -h or --help for help, and -v or --version for the installed version.
Environment overrides
See Configuration for FX_PROVIDER, FX_MODEL, FX_PERMISSION_MODE, and other environment variables.