---
title: "CLI"
description: "Install the Hoplite CLI, authenticate, and see every command"
canonical_url: "https://hoplite.sh/docs/cli"
markdown_url: "https://hoplite.sh/docs/cli.md"
---

# CLI
URL: /docs/cli
LLM index: /llms.txt
Description: Install the Hoplite CLI, authenticate, and see every command
Related: /docs/import, /docs/cli/handoff, /docs/cli/mcp-server, /docs/cli/acp, /docs/agent/skills

# CLI

The Hoplite CLI (`@usehoplite/cli`) imports local coding-agent history, hands the session you're actively working in to a live Hoplite agent, and manages skills. It supports **Claude Code**, **Codex**, and **OpenCode** sessions.

## Install

On macOS or Linux, use the native installer. It downloads a versioned release archive, verifies its SHA-256 checksum, and installs to `~/.local/bin` without modifying your shell configuration:

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

The installer does not modify your `PATH`. Use `$HOME/.local/bin/hoplite` as shown, or add that directory to your shell configuration before using the bare `hoplite` command.

On Windows, paste this into Command Prompt or PowerShell. It explicitly starts PowerShell, so it does not depend on the `irm` or `iex` aliases:

```powershell title="Windows terminal"
powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "Invoke-RestMethod -Uri 'https://hoplite.sh/install.ps1' | Invoke-Expression; & (Join-Path ([Environment]::GetFolderPath('LocalApplicationData')) 'Hoplite\bin\hoplite.exe') onboard"
```

`onboard` scans your machine for local session history from supported tools, shows what it found, and imports it. See [Import your history](/docs/import) for what gets imported and how MCP credentials are handled.

## Package-manager alternative

The npm package remains available when native installation is not an option:

```bash title="terminal"
npx -y @usehoplite/cli onboard
```

When running from a pnpm project, prefer pnpm so its workspace protocols are understood:

```bash title="terminal"
pnpm dlx @usehoplite/cli onboard
```

If npm reports `EOVERRIDE`, it is validating the current repository's `package.json` before Hoplite starts. Run it from a temporary directory instead:

```bash title="terminal"
cd "$(mktemp -d)" && npx -y @usehoplite/cli onboard
```

## Authentication

The CLI authenticates with an API key. Create one under **Settings → Workspace → API keys** — the same keys work for scripts and other API automation.

## Manage skills

Skills are versioned instruction bundles that Hoplite agents can load while working in a project — the deep dive lives at [Skills](/docs/agent/skills).

Create a project skill in the current repository with a concise description of when it applies:

```bash title="terminal"
hoplite skills add release-check --description "Prepare and verify a production release"
```

The command creates `.agents/skills/release-check/SKILL.md`, the standard project skill location. Add the project-specific workflow to that file and commit it; agents see it when they work from the repository. Use `hoplite skills list` to inspect the skills available from `.agents/skills` and the compatible `.claude/skills` location.

To copy selected skills you installed locally with `npx skills add ... --global` into your personal Hoplite library, run:

```bash title="terminal"
hoplite skills import-global --name <skill-name>
```

Initial `hoplite onboard` presents these global skills as a default-selected personal-skills step before the final confirmation. You can still run the command later to add selected skills, use `--all --yes` for an explicit bulk import, or use `--replace` to overwrite a same-named personal skill. Every import reads only the root `SKILL.md` instructions. Personal skills apply only to projects you start, never to automations, and repository skills take precedence when names collide.

## Commands

| Command | What it does |
| --- | --- |
| `onboard` | Scan local Claude Code / Codex / OpenCode history, select global personal skills, and [import them](/docs/import) |
| `handoff` | [Start a live cloud thread](/docs/cli/handoff) from the current local agent session |
| `skills add <name>` | Create a versioned project skill in `.agents/skills` |
| `skills import-global` | Add selected local global skills to your personal library |
| `skills list` | List project skills available to Hoplite agents |
| `undo` | [Reverse a previous import](/docs/import) |
| `mcp start` | Authorize [Hoplite's MCP server](/docs/cli/mcp-server) via browser OAuth and store the token |

## Verify a download

Every native download contains `checksums.txt` for its immutable archives. You can install a specific version and destination with:

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

## Sitemap

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