---
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`.

### MCP servers on your machine

`localMcpServers` in `~/.hoplite/settings.json` configures the MCP servers that [`--mcp`](/docs/cli/interactive#mcp-servers-on-your-machine) would, for every session:

```json
{
  "localMcpServers": {
    "paper": "http://127.0.0.1:29979/mcp",
    "notes": { "url": "http://localhost:4001/mcp", "write": true, "trust": false }
  }
}
```

A server is a URL, or an object with `url` and the optional `write` and `trust` flags. `--mcp` flags take precedence over `HOPLITE_LOCAL_MCP`, and both over `settings.json`, for a server of the same name. A repository's `.hoplite.json` can't add servers: only you can let the agent reach your machine.

### Commands on your machine

`localExec` in `~/.hoplite/settings.json` opts this computer in to [local commands](/docs/cli/interactive#commands-on-your-machine) for every session, as `--local-exec` does, and holds your rules:

```json
{
  "localExec": {
    "enabled": true,
    "allow": ["xcodebuild", { "command": "xcrun devicectl", "dir": "/Users/me/code/app" }]
  }
}
```

A rule is the words a simple command starts with (one to three), or an object with `command` and an absolute `dir`. Without `dir`, a rule covers the repository you start `hoplite` in. Like `localMcpServers`, this key is read only from your own `settings.json`, never from a repository's `.hoplite.json`.

## Credentials

New sign-ins store API keys in macOS Keychain or, on Linux, an unlocked Secret Service accessed through `secret-tool`. Install your distribution's package providing `secret-tool` and start or unlock your Secret Service before running `hoplite login`. Without secure storage, login fails rather than saving a plaintext key; set `HOPLITE_API_KEY` to a `hop_` API key instead. The CLI uses that key in place of any stored sign-in, never writes it to disk, and doesn't need the credentials directory, so it also works where that directory can't be created safely.

Account metadata lives in `$XDG_CONFIG_HOME/hoplite/credentials.json`, or `~/.config/hoplite/credentials.json` when `XDG_CONFIG_HOME` is unset. Existing plaintext credential entries are migrated to secure storage when loaded, and the persisted API key is replaced with metadata. If secure storage is unavailable, that entry is left intact for a later retry and is not used. Other accessible workspace credentials remain usable. Failed key reads, remote revocation, or secure-storage deletion during logout retain cleanup-only credentials so a later logout can retry without using that key for authentication. Legacy plaintext keys remain in their existing entry until revocation succeeds; new secure-storage keys stay in secure storage.

Replacement sign-ins first persist the new key in a separate secure-storage slot and its metadata before revoking the previous key. Failed persistence leaves the previous credential usable. Failed revocation or deletion retains cleanup-only metadata for a later login or logout to retry. Downgrading to an older CLI that does not understand these slots requires signing in again. `HOPLITE_BROWSER` selects the browser executable; setting `NO_BROWSER` suppresses automatic browser launch, including background sign-ins.

## 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/thread-list-cache.json` | The last `/resume` list per repository, scope, and account (titles, status, author, branch, and pull request, never messages), with `0600` permissions. The picker shows it while the fresh list loads |
| `~/.hoplite/projects.json` | The project `/project` picked for each checkout, so the next session there starts in it |
| `~/.hoplite/` | Prompt history, logs, custom themes, and the last update check (`update-check.json`) |



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. Once you configure [MCP servers on your machine](/docs/cli/interactive#mcp-servers-on-your-machine), connections to your own machine are limited to their ports and, for a local server, the Hoplite API's. 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: `git`, the browser that opens links, and [local commands](/docs/cli/interactive#commands-on-your-machine) you approve.

## Environment variables

| Variable | What it does |
| --- | --- |
| `HOPLITE_API_KEY` | A `hop_` API key to use instead of any stored sign-in. It's never written to disk, and no browser sign-in starts while it's set: if Hoplite rejects it, replace the key or unset it |
| `HOPLITE_PROJECT_ID` | Use this project instead of the one linked to the repository's Git remote, or the one `/project` saved for the checkout. `hoplite acp` also takes `--project` |
| `HOPLITE_BASE_URL` | Hoplite API origin, for a staging or local server. Default `https://api.hoplite.sh` |
| `HOPLITE_BROWSER` | Program that opens the sign-in page. `none` only prints the URL |
| `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_LOCAL_MCP` | [MCP servers on your machine](/docs/cli/interactive#mcp-servers-on-your-machine), as `--mcp` takes them, separated by commas: `paper=http://127.0.0.1:29979/mcp,write,notes=http://localhost:4001/mcp`. A bare `write` or `trust` applies to the server before it |

### 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_LOCAL_MCP_VERBOSE` | `1` prints each local MCP registration and call to stderr |
| `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 |

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