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

## 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`) |
| `~/.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. Use an absolute path to a private user configuration directory.

Credential storage rejects unsafe paths or permissions and does not fall back to shared temporary storage when no user configuration directory is available. On Unix, the private Hoplite directory and credential files must belong to your account and deny access to other users; newly created directories use `0700` and files use `0600`. Fix unsafe ownership or permissions before signing in again.

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: its `hoplite-legacy` helper, `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_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_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` |
| `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 |
| `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

Sitemap discovery is not enabled for this deployment.