# @cursell/cli

The Cursell command-line interface for the [Agent Hub](https://cursell.ai) —
discover, install, and use specialized AI agents across Claude Code, Codex
CLI, and Gemini CLI.

## Install

```bash
npm install -g @cursell/cli
```

Or run without installing:

```bash
npx @cursell/cli hub init
```

## Quick start

Point Cursell at your AI CLI of choice:

```bash
cursell hub init
```

This detects Claude Code, Codex CLI, or Gemini CLI on your system and
configures the MCP server + skill files automatically. From then on, ask
your AI to load a Cursell agent by its `<username>/<slug>` ref:

```
Load alice/vibesec and review this code.
```

Pin agents to a project so the team always loads the same versions:

```bash
cursell add alice/vibesec       # writes cursell.lock
cursell update                  # refresh pinned versions
cursell verify                  # check the lockfile against the registry
```

The CLI rejects bare slugs (`cursell add vibesec`) with a
`missing_namespace` error — every ref must include the publisher's
username so two authors can each ship a `vibesec` without collision.

## Commands

| Command | What it does |
|---|---|
| `cursell hub init` | Configure your AI CLI to use the Cursell Hub |
| `cursell hub init --provider <name>` | Configure only for `claude`, `codex`, or `gemini` |
| `cursell hub init --with-statusline` | Also add a Claude Code statusline that shows the active agent per terminal |
| `cursell hub init --use-npx` | Write npx-based entries (no global install needed) |
| `cursell hub update` | Refresh skill / instruction files |
| `cursell hub login` | Authenticate with the Cursell Hub |
| `cursell add <username>/<slug>` | Pin an agent in the project's `cursell.lock` |
| `cursell update` | Re-fetch the latest version of each pinned agent |
| `cursell remove <username>/<slug>` | Unpin an agent |
| `cursell verify` | Check that pinned versions still resolve to their recorded hashes |
| `cursell install` | Hydrate the local cache from `cursell.lock` (CI-friendly) |
| `cursell --help` | Show all commands |
| `cursell --version` | Print the installed version |

## How it works

Three binaries ship in this package:

- **`cursell`** — the CLI you run manually
- **`cursell-mcp`** — the MCP (Model Context Protocol) server your AI CLI
  talks to. Tools: `search_agents` (results carry `canonicalRef`),
  `load_agent({ref: "<username>/<slug>"})`,
  `list_loaded()` (agents loaded into the current session),
  `list_pinned()` (agents pinned in `cursell.lock`; no input,
  rows expose `ref`), plus author-side `preview_agent`,
  `edit_agent({ref})`, `publish_agent`. The `ref` parameter — not
  `slug` — is the canonical name; bare slugs are rejected with
  `missing_namespace`.
- **`cursell-statusline`** — optional per-session status line for Claude
  Code that shows which agent is currently loaded

When you load an agent, the MCP server fetches its instructions from the
Cursell Hub, caches it locally under `~/.cursell/cache/`, and your AI CLI
follows those instructions for the rest of the session.

## Documentation

Full documentation lives at <https://github.com/cursell/cli>:

- [Installation](https://github.com/cursell/cli/blob/main/docs/installation.md)
- [Configuration](https://github.com/cursell/cli/blob/main/docs/configuration.md)
- [Claude Code setup](https://github.com/cursell/cli/blob/main/docs/providers/claude-code.md)
- [Codex CLI setup](https://github.com/cursell/cli/blob/main/docs/providers/codex-cli.md)
- [Gemini CLI setup](https://github.com/cursell/cli/blob/main/docs/providers/gemini-cli.md)
- [Troubleshooting](https://github.com/cursell/cli/blob/main/docs/troubleshooting.md)

## Support

- **Bug reports / feature requests:** [open an issue](https://github.com/cursell/cli/issues)
- **Security vulnerabilities, hub / account questions, anything else:** contato@cursell.com

## License

Apache 2.0 — see [LICENSE](./LICENSE).