---
title: CLI Reference
description: Every ai command, flag, and in-session slash command for the TheGitAI CLI in one place.
---

# CLI Reference

A complete reference for the `ai` command.

## Usage

```bash
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](/docs/core-features/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. |

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