---
title: "CLI configuration"
description: "CLI settings, the files the Hoplite CLI keeps on your machine, and its environment variables."
canonical_url: "https://hoplite.sh/docs/cli/configuration"
markdown_url: "https://hoplite.sh/docs/cli/configuration.md"
---

# CLI configuration
URL: /docs/cli/configuration
LLM index: /llms.txt
Description: CLI settings, the files the Hoplite CLI keeps on your machine, and its environment variables.
Related: /docs/cli, /docs/cli/interactive, /docs/workspace/troubleshooting

# CLI configuration

The Hoplite CLI needs no configuration: sign in, then run it from a repository linked to a Hoplite project. This page covers what you can change.

## Settings

`/settings` browses and changes the CLI's settings, grouped by category:

| Setting | What it does |
| --- | --- |
| Status line session, Status line workspace | Show the thread title, or the workspace path and Git branch, in the status line (also `/statusline`) |
| Slash menu categories | Group slash-command results by category |
| Collapse tool calls | Show one summary line for each group of tool calls |
| Sound level | `off`, `on`, or `max` for sounds and terminal bells |
| Startup scrollback | Restore earlier terminal output when the CLI starts |
| Prompt history | Save the prompts and slash commands you send, for **Up** and **Down** |

Settings are saved in `~/.hoplite/settings.json`. A repository can override some of them in a `.hoplite.json` file at its root.

The CLI follows your terminal's light or dark mode. To pin a theme, set `"theme"` in `settings.json` or `HOPLITE_THEME` to `light`, `dark`, or the name of a custom theme in `~/.hoplite/themes/NAME.json`.

## Files on your machine

| Path | Contents |
| --- | --- |
| `~/.hoplite/settings.json` | Your CLI settings |
| `~/.hoplite/threads.json` | The threads you used from this machine: ID, repository, title, and when you last used it. Used by `-c`, `-r`, and the offline `/resume` list |
| `~/.hoplite/` | Prompt history, logs, custom themes, and the last update check (`update-check.json`) |
| `~/.config/hoplite/credentials.json` | The index of your signed-in workspaces. On macOS the keys themselves are in the Keychain; elsewhere they are in this file with `0600` permissions |
| `~/.config/hoplite/mcp-oauth.json` | The token stored by `hoplite mcp start` |

When `XDG_CONFIG_HOME` is set, the two `~/.config/hoplite` files are in `$XDG_CONFIG_HOME/hoplite` instead. `~/.hoplite` doesn't move.

Conversations stay in Hoplite. The CLI keeps no transcripts on your machine.

## Network

The `hoplite` binary connects only to the Hoplite API. Lookups of any other host name fail, and connections must go to an address that an allowed lookup returned, or to your own machine. The CLI has no telemetry, analytics, crash reporting, or self-update.

The one exception is the update check. When you start the interactive CLI, at most once a day and in the background, it reads `https://hoplite.sh/downloads/latest.json`, the file the installer reads. The request carries no credentials or identifiers. If a newer release exists, the next launch shows one dim line naming how to upgrade, such as `Hoplite CLI 3.1.0 is available · npm i -g @usehoplite/cli@latest` (or `brew upgrade hoplite` for a Homebrew install). See [Upgrade](/docs/cli#upgrade). `hoplite ask` and `hoplite acp` never show it. Set `HOPLITE_NO_UPDATE_CHECK=1` to turn the check off.

Programs the CLI starts aren't covered by this restriction: its `hoplite-legacy` helper, `git`, and the browser that opens links.

## Environment variables

| Variable | What it does |
| --- | --- |
| `HOPLITE_PROJECT_ID` | Use this project when the repository's Git remote doesn't identify one, or to override it. `hoplite acp` also takes `--project` |
| `HOPLITE_BASE_URL` | Hoplite API origin, for a staging or local server. Default `https://api.hoplite.sh` |
| `HOPLITE_ORG_ID` | Organization ID that `login`, `onboard`, `update`, `undo`, `skills`, `mcp config`, and `auth status` use when you are signed in to several workspaces |
| `HOPLITE_API_KEY` | An [existing API key](/docs/cli#use-an-existing-api-key) for `onboard`, `update`, `undo`, `handoff`, `skills`, `mcp config`, and `auth`, used for that run only. Sessions use stored credentials only |
| `HOPLITE_BROWSER` | Program that opens the sign-in page. `none` only prints the URL |
| `XDG_CONFIG_HOME` | Directory for `hoplite/credentials.json` and `hoplite/mcp-oauth.json`. Default `~/.config` |
| `HOPLITE_THEME` | `light`, `dark`, or a custom theme name |
| `NO_COLOR` | Any non-empty value turns colour off, including in the interactive CLI ([no-color.org](https://no-color.org)). Bold, dim, reverse video for selections, and underlined links remain. `TERM=dumb` does the same |
| `HOPLITE_NO_UPDATE_CHECK` | `1` turns off the daily update check and its notice |
| `HOPLITE_SOUND` | `off`, `on`, or `max` |
| `HOPLITE_LEGACY_BIN` | Path to the `hoplite-legacy` helper. Default: next to `hoplite`. The CLI never looks for it on `PATH` |

### Development and debugging

| Variable | What it does |
| --- | --- |
| `HOPLITE_ACP_URL`, `HOPLITE_ACP_API_KEY` | Skip sign-in and project lookup: a full ACP URL (`…/acp?projectId=…`) and a `hop_` key, for local servers |
| `HOPLITE_ACP_CWD` | Working directory reported to new ACP sessions. Default `/workspace`, the sandbox checkout |
| `HOPLITE_TRACE` | `1` writes a debug trace to `~/.hoplite/logs/trace.log` |
| `HOPLITE_TRACE_LOG` | Write the debug trace to this path instead |
| `HOPLITE_TRACE_STDERR` | `1` also writes the trace to stderr |
| `HOPLITE_TRACE_SCOPES` | Limit the trace to these scopes |
| `HOPLITE_RECORD`, `HOPLITE_RECORD_INPUT` | Record the terminal session to a tape file |
| `HOPLITE_SYNC_UPDATES` | Force synchronized terminal updates on or off |
| `HOPLITE_UI_OBSERVE_DIR` | Write rendered frames to a directory, for UI debugging |
| `HOPLITE_KEYCHAIN`, `HOPLITE_KEYCHAIN_SERVICE` | Keychain file and service name for stored keys, for tests |

To share a trace with Hoplite support, run `/trace` in the session. It copies a private diagnostic trace.

## Sitemap

See the full [sitemap](/docs/sitemap.md) for all pages.
Well-known sitemap: [/docs/.well-known/sitemap.md](/docs/.well-known/sitemap.md).