# CLI

> Install the estelle CLI to index local repositories, configure MCP clients, capture sessions, and check code from a terminal.

The `estelle` CLI connects a local checkout to your Estelle account. Use it when you need to index uncommitted work, configure an editor without editing MCP files by hand, capture coding-agent sessions, or run repository checks from a terminal.

It runs natively on macOS and Linux on x86_64 and arm64. On Windows, install both the CLI and your coding agent inside WSL.

**Note:**
The CLI is optional. For native Claude Code, Codex, Kimi Code, Grok Build or Cursor plugins, use [Install Estelle](https://docs.fatelabs.ca/install). Those hooks run with external Node.js 22+ and an account key, without this CLI or a local MCP server. The legacy CLI's Node/platform requirements below are separate.

## Install and sign in

### Install the CLI

With npm on Node.js 18 or later:

```bash
npm i -g @fatelabs/estelle
```

Or use the release installer, which selects the build for your machine and verifies its checksum:

```bash
curl --proto '=https' --tlsv1.2 -fsSL \
  https://github.com/uqeu/estelle-cli/releases/latest/download/install.sh | sh
```

### Authenticate

Create a key in **Settings → API keys**, then run:

```bash
estelle login
```

Paste the key when prompted. Commands use the stored key or `ESTELLE_API_KEY` from the environment. `init` and `sweep` also accept a one-time `--key` option.

### Configure and index

From the repository root:

```bash
estelle init
estelle sweep --dry-run
estelle sweep
```

`init` detects supported editors, writes their MCP configuration, and checks the connection. The dry run lists files without sending them; the sweep indexes the checkout, including uncommitted content visible to git.

For the guided version of this workflow, run `estelle setup`. It configures the repository, sweeps it, and checks a real symbol from your code. Add `--dry-run` to preview the actions.

## Command reference

| Command | What it does |
|---|---|
| `estelle login` | Store and verify your Estelle API key. With `--provider`, configure a model account instead. |
| `estelle setup` | Run the guided configure, sweep, and verification workflow. |
| `estelle init` | Detect editors, write MCP configuration, and check it. `--client <name>` targets `cursor`, `vscode`, `windsurf`, or `jetbrains`. |
| `estelle connect <client>` | Print the setup command or configuration for one client. |
| `estelle remove` | Remove Estelle entries from editor configurations. |
| `estelle sweep` | Index the current repository. |
| `estelle reindex` | Update the index for changed files. |
| `estelle github link` | Link GitHub and connect an App installation from the terminal. |
| `estelle ask "<question>"` | Ask about your codebase using the context available to your account. |
| `estelle recall "<query>"` | Search memory and code together. Use `--repo owner/name` to scope a multi-repository account. |
| `estelle verify <file>` | Check a file for references that cannot be resolved against the indexed repository. |
| `estelle install-hooks` | Add Estelle's session hooks to Claude Code and Codex while preserving other hooks. |
| `estelle uninstall-hooks` | Remove only Estelle's hooks. |
| `estelle mcp-server` | Serve Estelle's MCP tools over stdio for a local client. |
| `estelle acp` | Serve Estelle as an Agent Client Protocol agent over stdio. |
| `estelle leaked` | Scan your own `~/.claude` and `~/.codex` for exposed credentials offline, printing rule, fingerprint, path, and line rather than the value. |
| `estelle doctor` | Diagnose credential and setup problems without printing secrets. |
| `estelle upgrade` | Report whether a newer release exists and print its install command. It does not install the release. |
| `estelle --version` | Print the installed version. |

Run `estelle <command> --help` for the flags supported by your installed version.

## Keep an index current

```bash
cd path/to/your/repo
estelle reindex
```

Use `reindex` after ordinary edits and `sweep` again after substantial changes. Navigation answers come from the last content you indexed; an older index can be reported as stale. To index code available through GitHub instead, use the [GitHub connection](https://docs.fatelabs.ca/github).

Check one file before sharing or committing it:

```bash
estelle verify src/api/routes.py
```

For a fuller review of a change, use `/review` in an Estelle session or open a pull request for [Prism](https://docs.fatelabs.ca/prism). Your own build and test commands still belong in CI.

## Capture Claude Code and Codex sessions

```bash
estelle install-hooks
```

This writes Estelle's hooks to `~/.claude/settings.json` and `~/.codex/hooks.json`, or `$CODEX_HOME/hooks.json` when `CODEX_HOME` is set. Restart Claude Code or open `/hooks` to activate them. In Codex, run `/hooks` and trust Estelle's hooks; untrusted hooks cannot record sessions.

Captured sessions appear under [Sessions](https://docs.fatelabs.ca/sessions) and can feed [Memory](https://docs.fatelabs.ca/memory).

## Configure a model for the terminal

Run `estelle` without a subcommand to open the terminal interface. Use `/login` to connect a model account and `/model` to select a model. You can also configure one from the shell:

```bash
estelle login --provider anthropic-api
```

Other supported provider names include `openai-api`, `gemini`, `deepseek`, `openrouter`, `ollama`, and `lmstudio`. For another OpenAI-compatible endpoint:

```bash
estelle login --provider openai-compatible \
  --base-url "YOUR_PROVIDER_API_BASE" \
  --model "YOUR_MODEL_ID"
```

## What leaves your machine

- `sweep` sends repository content; the dry run sends none.
- `verify` sends the file you name.
- `ask` and `recall` send your question and relevant account context.
- `init`, `connect`, and `remove` change local configuration, apart from the connection check performed by `init`.
- `leaked` runs fully offline.

Use `estelle doctor` after changing credentials or client configuration. `estelle upgrade` only checks for a release; reinstall with npm or the installer to apply one.

## Limits

- There is no native Windows build. Use WSL for both the CLI and the coding agent so session hooks can find the executable.
- An index does not update itself after local edits. Reindex or sweep before relying on current code navigation.
- The hooks record sessions only after they are installed and, in Codex, trusted.

## Related

- [Install Estelle](https://docs.fatelabs.ca/install): Choose the plugin, CLI, or hosted MCP setup.
- [MCP server](https://docs.fatelabs.ca/mcp): Connect clients and choose tools by task.
- [Troubleshooting](https://docs.fatelabs.ca/troubleshooting): Fix sign-in, connection, and indexing problems.