---
title: "CLI"
description: "Import your local Claude Code, Codex, or OpenCode history into Hoplite"
canonical_url: "https://hoplite.sh/docs/cli"
markdown_url: "https://hoplite.sh/docs/cli.md"
---

# CLI
URL: /docs/cli
LLM index: /llms.txt
Description: Import your local Claude Code, Codex, or OpenCode history into Hoplite
Related: /docs/getting-started, /docs/workspace

# CLI

The Hoplite CLI (`@usehoplite/cli`) imports your local coding-agent history — **Claude Code**, **Codex**, and **OpenCode** sessions — and your selected personal global skills into Hoplite, so the context you've built up locally comes with you.

## Personal global skills

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

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

## Install and import your history

On macOS, install the native CLI from Hoplite's official Homebrew tap:

```bash title="terminal"
brew install CarbonCopyInc/tap/hoplite
hoplite onboard
```

On macOS or Linux without Homebrew, use the 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
hoplite onboard
```

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

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

`onboard` scans your machine for local session history from supported tools, shows what it found, and imports it. It's the same step offered during [onboarding](/docs/getting-started#4-import-your-history-optional), and you can run it any time.

## Undo an import

```bash title="terminal"
hoplite undo
```

Removes what a previous `onboard` run imported.

## Add project skills

Skills are versioned instruction bundles that Hoplite agents can load while
working in a project. Create one 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.

## Authentication

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

## Commands

| Command | What it does |
| --- | --- |
| `onboard` | Scan local Claude Code / Codex / OpenCode history, select global personal skills, and import them |
| `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 |
| `mcp start` | Authorize [Hoplite's MCP server](/docs/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).