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, replay, 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.
`fx replay <tape>`	Replay a recorded terminal session. Accepts `--frames`, `--golden <path>`, and `--frames-dir <path>`.

See Sessions for the full workflow.

Account and configuration

Command	Purpose
`fx login`	Sign in with Vercel.
`fx logout`	Sign out of the current saved Vercel session.
`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.
`fx models`	List available models.
`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. See Authentication.

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. --record is also accepted after resume.

--record records visible terminal output.
--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.
-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.