CLI

The Hoplite CLI (@usehoplite/cli) is Hoplite's coding agent in your terminal. Every prompt runs on a Hoplite thread 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 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#

npm i -g @usehoplite/cli

On macOS you can use Homebrew instead:

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:

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

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:

Invoke-WebRequest https://hoplite.sh/downloads/releases/3.0.0/hoplite_3.0.0_windows_amd64.zip -OutFile hoplite_3.0.0_windows_amd64.zipInvoke-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):

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:

curl -fsSLO https://hoplite.sh/downloads/releases/3.0.0/hoplite_3.0.0_darwin_arm64.tar.gzcurl -fsSLO https://hoplite.sh/downloads/releases/3.0.0/checksums.txtgrep ' 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:

npm i -g @usehoplite/cli@latestbrew 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).

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:

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:

cd path/to/your-repohoplite

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.

Interactive sessions covers the composer, queueing and steering, threads, and shortcuts. For one-off or scripted requests, use hoplite 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.

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:

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#

Run hoplite COMMAND --help for a command's flags. Inside a session, /help lists the slash commands.

Use Hoplite in Zed or Paseo#

hoplite acp runs the CLI as a local Agent Client Protocol 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.

What's in this section#

Problems with installing, signing in, or connecting are covered in Troubleshooting.

Acknowledgements#

The interactive CLI is built on 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: