> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withterminal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Configuration, global options, and commands for the Terminal CLI.

<Warning>
  The Terminal CLI is in **beta**. Commands, flags, and arguments may change
  before a 1.0 release. Please share feedback via our shared Slack channel or
  [support@withterminal.com](mailto:support@withterminal.com).
</Warning>

The [Terminal CLI](https://github.com/terminal-api/terminal-cli) is an open-source command line for the Terminal API, published as [`@terminal-api/cli`](https://www.npmjs.com/package/@terminal-api/cli). Its commands are generated from the Terminal OpenAPI spec. For setup steps, see the [Agents guide](/guides/agents#cli).

```bash theme={null}
npm install -g @terminal-api/cli
```

## Configuration

The CLI authenticates with a secret key and, for connection-scoped commands, a connection token. See [Authentication](/api-reference/authentication).

```bash theme={null}
terminal config set api-key sk_prod_xxx
terminal config set connection-token con_tkn_xxx
```

| Config key         | Environment variable        | Description                                                                   |
| ------------------ | --------------------------- | ----------------------------------------------------------------------------- |
| `api-key`          | `TERMINAL_API_KEY`          | Secret key from the [Dashboard](https://dashboard.withterminal.com/api-keys)  |
| `connection-token` | `TERMINAL_CONNECTION_TOKEN` | Connection token sent as the `Connection-Token` header                        |
| `environment`      | `TERMINAL_ENVIRONMENT`      | `prod` or `sandbox`. Selects the [environment](/api-reference/environments)   |
| `base-url`         | `TERMINAL_BASE_URL`         | Overrides the API base URL. Defaults to `https://api.withterminal.com/tsp/v1` |

Environment variables take precedence over the config file. The config file lives at `~/.terminal/config.json`; `terminal config show` prints the active values and `terminal config path` prints the file location.

### Profiles

Profiles keep separate credentials, for example sandbox and production. The CLI ships with `prod` (default) and `sandbox` profiles.

```bash theme={null}
terminal config set api-key sk_sandbox_xxx --profile sandbox
terminal list-vehicles --profile sandbox

terminal profile create staging
terminal profile use sandbox
terminal profile list
```

Set `TERMINAL_PROFILE` to choose a profile without passing `--profile`.

## Usage

```bash theme={null}
terminal <command> [options]
```

Run `terminal` with no arguments to open an interactive TUI for browsing and running commands.

### Global options

| Option                       | Description                                              |
| ---------------------------- | -------------------------------------------------------- |
| `--format <format>`          | Output format: `json` (default), `pretty`, or `table`    |
| `--api-key <key>`            | Overrides the configured secret key                      |
| `--connection-token <token>` | Overrides the configured connection token                |
| `--profile <name>`           | Uses a specific config profile                           |
| `--all`                      | Follows `next` cursors and returns every page of results |
| `--help`, `-h`               | Shows help                                               |
| `--version`, `-v`            | Shows the CLI version                                    |

## Commands

Each Terminal API operation is a command named after the operation in kebab-case. For example, [List Vehicles](/api-reference/vehicles/list-vehicles) is `terminal list-vehicles`. Unlike the [MCP server](/api-reference/mcp), the CLI includes write operations such as [passthrough](/api-reference/data-management/passthrough) and [request sync](/api-reference/data-management/request-sync).

Path, query, and body parameters are flags with the same names as the API parameters:

```bash theme={null}
terminal get-vehicle --id vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC
terminal list-historical-vehicle-locations \
  --vehicleId vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC \
  --startAt 2026-01-01T00:00:00Z \
  --endAt 2026-01-02T00:00:00Z
terminal list-drivers --limit 10 --all
```

Commands are grouped the same way as the API reference: `authentication`, `connections`, `data-management`, `devices`, `drivers`, `fault-codes`, `groups`, `hours-of-service`, `ifta`, `issues`, `link`, `providers`, `safety`, `trailers`, `trips`, `vehicle-utilization`, and `vehicles`. Run `terminal --help` for the full list, or `terminal <command> --help` for a command's flags.

### Response schemas

Append `schema` to any command to print its response schema without calling the API:

```bash theme={null}
terminal list-vehicles schema
```

### Shell completions

```bash theme={null}
eval "$(terminal completions bash)"   # ~/.bashrc
eval "$(terminal completions zsh)"    # ~/.zshrc
terminal completions fish > ~/.config/fish/completions/terminal.fish
```

## Agent skills

The CLI repo ships [skills and commands](https://github.com/terminal-api/terminal-cli/tree/main/ai) for Cursor, Claude Code, and OpenCode. Copy them into your project so the agent knows how to call the CLI.

## Rate limits

CLI commands are ordinary Terminal API requests and count toward the same [rate limits](/api-reference/rate-limits). `--all` fetches pages one at a time.