---
title: "CLI"
description: "Run Hoplite's coding agent from your terminal, script it with hoplite ask, and connect local ACP clients."
canonical_url: "https://hoplite.sh/docs/cli"
markdown_url: "https://hoplite.sh/docs/cli.md"
---

# CLI
URL: /docs/cli
LLM index: /llms.txt
Description: Run Hoplite's coding agent from your terminal, script it with hoplite ask, and connect local ACP clients.
Related: /docs/cli/interactive, /docs/cli/commands, /docs/cli/ask, /docs/cli/acp, /docs/import

# CLI

The Hoplite CLI (`@usehoplite/cli`) is Hoplite's coding agent in your terminal. Every prompt runs on a Hoplite [thread](/docs/threads) in your project's cloud sandbox, and the CLI streams back the answer, tool calls, and approval requests. Nothing runs on your machine, and the CLI talks only to the Hoplite API, apart from a once-a-day [update check](/docs/cli/configuration#network) against `hoplite.sh`.

Because the work lives in a thread, you can open the same conversation in the Hoplite app, share it with teammates, and pick it up again from any terminal.

## Install

```bash title="terminal"
npm i -g @usehoplite/cli
```

On macOS you can use Homebrew instead:

```bash title="terminal"
brew install usehoplite/tap/hoplite
```

Or, without npm or Homebrew on macOS and Linux, run the install script. It installs `hoplite` and `hoplite-legacy` in `~/.local/bin` after checking the release checksum, and needs no `sudo`:

```bash title="terminal"
curl -fsSL https://hoplite.sh/install.sh | sh
```

npm and Homebrew install the `hoplite` command and its short alias `hplt`. Native release archives for macOS, Linux, and Windows are listed with their sizes and SHA-256 checksums on the [download page](https://hoplite.sh/download), and published under `https://hoplite.sh/downloads/releases/<version>/` with a `checksums.txt` per release; `https://hoplite.sh/downloads/latest.json` names the current version. A macOS or Linux archive contains `hoplite` and its `hoplite-legacy` helper; keep the two in the same directory.

<Callout type="info" title="Windows">
On Windows, `hoplite` provides the sign-in, import, handoff, skills, and MCP commands. The interactive agent, `hoplite ask`, `hoplite exec`, `hoplite shell`, `hoplite push`, `hoplite status`, and `hoplite acp` are available on macOS and Linux only.
</Callout>

On Windows, install with npm as above. Without npm, download the archive for your architecture (`amd64` or `arm64`) and the release's `checksums.txt`, then compare the two hashes before extracting `hoplite.exe`:

```powershell title="PowerShell"
Invoke-WebRequest https://hoplite.sh/downloads/releases/3.0.0/hoplite_3.0.0_windows_amd64.zip -OutFile hoplite_3.0.0_windows_amd64.zip
Invoke-WebRequest https://hoplite.sh/downloads/releases/3.0.0/checksums.txt -OutFile checksums.txt
(Get-FileHash -Algorithm SHA256 hoplite_3.0.0_windows_amd64.zip).Hash.ToLower()
Select-String ' hoplite_3.0.0_windows_amd64.zip$' checksums.txt
```

### Verify a download

Every release's native downloads include a `checksums.txt` with the SHA-256 of each archive, and the install script checks it before extracting anything. To install a specific version, or into another directory, pass `--version` and `--install-dir` (or set `HOPLITE_INSTALL_DIR`):

```bash title="terminal"
curl -fsSL https://hoplite.sh/install.sh | sh -s -- --version 3.0.0 --install-dir "$HOME/.local/bin"
```

To check an archive you downloaded yourself, compare it with its line in the release's `checksums.txt`:

```bash title="terminal"
curl -fsSLO https://hoplite.sh/downloads/releases/3.0.0/hoplite_3.0.0_darwin_arm64.tar.gz
curl -fsSLO https://hoplite.sh/downloads/releases/3.0.0/checksums.txt
grep ' hoplite_3.0.0_darwin_arm64.tar.gz$' checksums.txt | shasum -a 256 -c
```

On Linux, `sha256sum -c` works the same way.

## Upgrade

The CLI does not update itself. Upgrade with the tool you installed it with:

```bash title="terminal"
npm i -g @usehoplite/cli@latest
brew upgrade hoplite
```

If you used the install script, run it again. `hoplite --version` prints the installed version. When a newer release is out, the interactive CLI says so in one line at startup (see [Network](/docs/cli/configuration#network)).

### Upgrading from 2.x

Version 3 makes `hoplite` Hoplite's coding agent in your terminal. The 2.x commands still work, but you'll be asked to sign in once after upgrading. Keys stored by 2.x keep working for `onboard`, `update`, `undo`, `handoff`, `skills`, and `mcp`, but they lack the permissions the agent needs to continue and stop runs, so Hoplite refuses them for sessions. The first `hoplite`, `hoplite ask`, or `hoplite acp` then signs you in again in the browser and stores a new key. In a script, where nobody can sign in, `hoplite ask` and `hoplite exec` stop with a message to run `hoplite login` once after upgrading. On macOS, keys move to the Keychain the first time they are read. What changed:

| 2.x | 3.x |
| --- | --- |
| `hoplite` with no command started the history import | `hoplite` starts an [interactive session](/docs/cli/interactive). Run `hoplite onboard` to import |
| `hoplite --headless`, `hoplite --org-id ID` | `hoplite onboard --headless`, `hoplite onboard --org-id ID` |
| `hoplite version` | `hoplite --version` |
| Signed in during `hoplite onboard` only | `hoplite login` and `hoplite logout`; `hoplite`, `hoplite ask`, and `hoplite acp` also sign in on first use |
| `hoplite completion` printed shell completion scripts | Removed on macOS and Linux |

`onboard`, `update`, `undo`, `handoff`, `skills`, `mcp`, and `auth` take the same flags as before, including `--api-key` and `HOPLITE_API_KEY`. `hoplite ask`, `hoplite exec`, `hoplite shell`, `hoplite acp`, and `hoplite status` are new in 3.0. On Windows, `hoplite` is still the 2.x command set with `login` and `logout` added.

If you go back to 2.x on macOS, sign in again there: 2.x can't read keys from the Keychain, so it treats you as signed out. The Keychain items stay until you run `hoplite logout` with 3.x or delete them in Keychain Access.

## Start a session

Run `hoplite` from a repository that is linked to a Hoplite project:

```bash title="terminal"
cd path/to/your-repo
hoplite
```

The CLI finds the project from the repository's GitHub remote. If more than one project links the same repository, it uses your saved `/project` choice, or the project with the most recently used thread. If neither has a clear answer, use `/project` or set `HOPLITE_PROJECT_ID`. See [Configuration](/docs/cli/configuration).

[Interactive sessions](/docs/cli/interactive) covers the composer, queueing and steering, threads, and shortcuts. For one-off or scripted requests, use [`hoplite ask`](/docs/cli/ask).

## Sign in

The first time you run `hoplite` or `hoplite ask`, the CLI opens your browser to sign in. On the approval page you choose the workspace, and the CLI stores a CLI key for it. You don't need to create an API key.

| Command | What it does |
| --- | --- |
| `hoplite login` | Sign in again, or sign in ahead of time |
| `hoplite login --org SLUG` | Add another workspace, or switch to one you already signed in to. The last workspace you sign in to becomes the default outside a linked repository |
| `hoplite logout` | Sign out: revoke every CLI key stored for this API on Hoplite, then remove them |

`hoplite logout` acts on one API at a time, the one `HOPLITE_BASE_URL` or `--base-url` names (by default Hoplite's), and leaves keys for other APIs alone. A key Hoplite can't revoke, for example while it's unreachable, is still removed, with a warning that it stays valid until it expires; revoke it under **Settings → Workspace → API keys**.

On macOS, keys are stored in the Keychain under the service **Hoplite CLI**. `~/.config/hoplite/credentials.json` keeps an index without secrets (`$XDG_CONFIG_HOME/hoplite/credentials.json` when `XDG_CONFIG_HOME` is set). On other systems, or when no keychain is writable, keys are stored in that file with owner-only permissions (`0600`). Keys that an older version stored in the file move to the Keychain the first time they are read.

If you start several sessions at once while signed out, they share a single browser sign-in.

### Use an existing API key

To use a key you already have, for example in CI, create one under **Settings → Workspace → API keys**. `hoplite onboard`, `update`, `undo`, `handoff`, `skills`, `mcp config`, and `auth` accept it in one of three ways. When more than one is present, the CLI uses the first in this order:

1. **The `--api-key` flag**, such as `hoplite handoff --api-key hop_...`. It's convenient for a one-off run, but the key lands in your shell history.
2. **The `HOPLITE_API_KEY` environment variable**, which suits CI secrets and keeps the key out of history.
3. **Stored credentials**, written by `hoplite login`, `hoplite onboard`, or `hoplite auth login`.

A key from the flag or the environment is used for that run only and never written to disk. Sessions (`hoplite`, `ask`, `acp`, `exec`, and `shell`) use stored credentials only. To store an existing key for every command, pipe it to `auth login` so it stays out of shell history:

```bash title="terminal"
printf '%s\n' "$HOPLITE_API_KEY" | hoplite auth login --api-key-stdin
```

The CLI asks the API which workspace the key belongs to, so you don't pass an organization ID. `hoplite auth status` shows which key would be used, where it came from, and its workspace, with the key masked.

## Commands

| Command | What it does |
| --- | --- |
| `hoplite` | Start an [interactive session](/docs/cli/interactive) |
| `hoplite --resume`, `-c`, `-r` | [Resume a thread](/docs/cli/interactive#resume-a-thread) |
| `hoplite ask PROMPT` | [Run one request](/docs/cli/ask) without the interactive UI |
| `hoplite acp` | Run Hoplite as a [local ACP agent](/docs/cli/acp#local-acp-clients) for Zed, Paseo, and other ACP clients |
| `hoplite exec COMMAND` | [Run a command in a thread's sandbox](/docs/cli/commands#run-commands-in-the-sandbox) and exit with its status |
| `hoplite shell` | [Open a shell in a thread's sandbox](/docs/cli/commands#open-a-shell-in-the-sandbox), like `ssh` |
| `hoplite push` | [Send your uncommitted local changes to a thread's sandbox](/docs/cli/commands#send-local-changes-to-the-sandbox) |
| `hoplite status [--json]` | Show the CLI version, working directory, and Hoplite endpoint |
| `hoplite login`, `hoplite logout` | [Sign in and out](#sign-in) |
| `hoplite onboard` | Scan local Claude Code, Codex, OpenCode, and Cursor history and [import it](/docs/import) |
| `hoplite update` | Import new local sessions and refresh history you imported before |
| `hoplite undo` | [Remove the threads created by the last import](/docs/import) |
| `hoplite handoff` | [Continue your current local agent session](/docs/cli/handoff) as a live Hoplite thread |
| `hoplite skills add NAME` | Create a [project skill](/docs/agent/skills) in `.agents/skills` |
| `hoplite skills list` | List the project skills available to Hoplite agents |
| `hoplite skills import-global` | Add selected local global skills to your personal library |
| `hoplite mcp start` | Authorize [Hoplite's MCP server](/docs/cli/mcp-server) in the browser and store the token |
| `hoplite mcp config` | Print MCP client config that sends an API key to [Hoplite's MCP server](/docs/cli/mcp-server#api-keys) |
| `hoplite auth login` | Verify an existing API key and store it (`--api-key-stdin`, `--api-key`, or `HOPLITE_API_KEY`) |
| `hoplite auth status` | Show which API key the CLI would use and its workspace |

Run `hoplite COMMAND --help` for a command's flags. Inside a session, `/help` lists the [slash commands](/docs/cli/commands).

## Use Hoplite in Zed or Paseo

`hoplite acp` runs the CLI as a local [Agent Client Protocol](https://agentclientprotocol.com) agent, so editors and tools that start ACP agents as local processes can use Hoplite. It uses your stored sign-in, and each session runs in the project linked to the repository it opens. Setup for Zed and Paseo is in [Local ACP clients](/docs/cli/acp#local-acp-clients).

## What's in this section

| Page | What it covers |
| --- | --- |
| [Interactive sessions](/docs/cli/interactive) | The composer, queue and steer, approvals, threads, teammates, models, failures, and offline behavior |
| [Slash commands](/docs/cli/commands) | Every slash command, pull requests, previews, usage, and thread actions |
| [hoplite ask](/docs/cli/ask) | One-shot and scripted requests, JSON output, resuming threads |
| [Configuration](/docs/cli/configuration) | Settings, stored files, and environment variables |
| [Hand off a session](/docs/cli/handoff) | Continue a Claude Code, Codex, OpenCode, or Cursor session in Hoplite |
| [Hoplite MCP server](/docs/cli/mcp-server) | Drive Hoplite from Claude Code, Cursor, or another MCP client |
| [Hoplite ACP endpoint](/docs/cli/acp) | The ACP protocol, and setup for Zed and Paseo |

Problems with installing, signing in, or connecting are covered in [Troubleshooting](/docs/workspace/troubleshooting#the-cli-is-not-on-path).

## Acknowledgements

The interactive CLI is built on [fx](https://github.com/vercel-labs/fx) by Vercel, used under the Apache License 2.0 and modified by Hoplite to run on Hoplite threads. It also includes the Zig standard library and, on Linux, musl libc, both under the MIT License. Every macOS and Linux release ships these licenses and notices in a `third_party` folder:

| Installed with | Location |
| --- | --- |
| npm | `third_party` in the `@usehoplite/cli-<os>-<cpu>` package, next to its `bin` folder |
| Homebrew | `$(brew --prefix)/share/doc/hoplite/third_party` |
| The install script | `share/hoplite/third_party` next to the install directory: `~/.local/share/hoplite/third_party` by default |
| A release archive | `third_party`, next to `hoplite` |

## Sitemap

Sitemap discovery is not enabled for this deployment.