CLI Reference

A complete reference for the ai command.

Usage

ai                 # start an interactive session in the current repo
ai "<request>"     # start a session with <request> as the first message
ai [options]

Coding sessions require an interactive terminal on both stdin and stdout. Piped prompts and redirected coding output are rejected; commands such as --help, --version, whoami, --usage, and --list-sessions remain redirectable.

Auth

Command	Description
`ai`	Signs you in if you aren't, then starts a session.
`ai login`	The same thing; kept for muscle memory. Starts the session directly when you are already signed in.
`ai whoami`	Show the signed-in account.
`ai --usage`	Show account usage percentage and reset times.
`ai logout`	Sign out.

The sign-in screen opens your browser and, at the same time, prints a URL you can open on any other device and a box for an authorization code. Headless and remote machines need no separate command: open the URL wherever you have a browser, choose On another computer on that page, and paste the code it shows. Whichever route answers first signs you in.

Updates

When a newer release is published, ai says so on start, before the session opens, and offers two ways on:

Choice	What happens
Update now (selected; Enter)	Installs the new version with the package manager this copy came from, then asks you to run `ai` again so the whole session runs one version.
Skip	Starts the session on the version you have.

Update now is selected when the offer appears, so Enter takes the update. ↑/↓ move between the two rows and the number keys jump straight to one.

TheGitAI works best on the latest version, and an older CLI may not work optimally. Skipping covers that one start: the next start asks again, and a release cannot be silenced for good. Ctrl+C at the prompt quits without installing anything.

MCP servers

Command	Description
`ai mcp add <name> -- <command> [args...]`	Configure a local stdio server.
`ai mcp add --transport http <name> <url>`	Configure a remote Streamable HTTP server.
`ai mcp add-json <name> '<JSON>'`	Import a server configuration.
`ai mcp list`	Show configured servers without starting them.
`ai mcp get <name>`	Show metadata without credential values.
`ai mcp enable <name>` / `ai mcp disable <name>`	Enable or disable a server.
`ai mcp remove <name>`	Remove a server configuration.
`ai mcp --help`	Show header and environment-variable options.

Short setup options are -t / --transport, -e / --env, -H / --header, and -s user / --scope user. Only user scope is supported.

These commands work without a coding session or sign-in. Configuration applies to your user on this machine. See MCP Servers for Context7, Playwright, authentication and current limits.

Sessions

Command	Description
`ai --list-sessions`	List saved sessions for this repo.
`ai --session <id\|name>`	Resume a saved session by id or name.

Sessions are stored locally and scoped to the current repo. Local history can be listed and resumed from that computer. Continuing a session through the service requires the TheGitAI account used for that session. The five most recent sessions per repo are kept.

Options

Option	Description
`-y`, `--yes`	Start in Bypass all permissions mode.
`-h`, `--help`	Show help.

Chat commands

Used inside an interactive session:

Command	Description
`/help`	Show help.
`/mcp`	Check MCP connections and list available tools.
`/about`	Show the installed version and platform information.
`/usage`	Show account usage percentage and reset times.
`/model`	List supported models and pick one.
`/model <id>`	Switch the active model without clearing history.
`/resume`	Resume a saved session for this repo.
`/jobs`	Open the background jobs picker (browse, expand output, stop).
`/jobs output <id>`	Print a background job's full captured output.
`/jobs kill <id>`	Stop a background job by id.
`/report`	Open the private form for bugs and feature requests on the TheGitAI website.
`/new`	start a new conversation; this session remains saved
`/logout`	Sign out and quit.
`/exit`	Quit the session.

Environment

Variable	Description
`THEGITAI_SESSION_DIR`	Override the default local directory for saved sessions.

Run ai --help at any time to print this reference in your terminal.