# @repolensai/cli

RepoLens terminal client for:

- connecting a terminal session to the RepoLens web product
- linking a local repo checkout to a RepoLens board
- building local context packs for Codex or Claude
- publishing local structured outputs back into RepoLens

## Install

```bash
npm install -g @repolensai/cli
repolens doctor
repolens login --app-url https://repolens.ai
```

## Login

1. Sign into RepoLens on the web.
2. Run:

```bash
repolens login --app-url https://repolens.ai
```

3. Approve the terminal login in the browser.
4. Return to the terminal and let RepoLens finish login automatically.

On macOS, RepoLens stores the token in Keychain when available. Other platforms use the local RepoLens config file with restrictive permissions.

Manual fallback: `repolens login --app-url https://repolens.ai --token <token>` still works when browser approval is not available.

RepoLens can register a custom `repolens-cli://` protocol for one-click handoff from the web app into the local CLI. On macOS, Linux, and Windows, `repolens login` attempts to install RepoLens Launcher automatically. Copy-and-run remains the fallback when protocol support is unavailable.

On macOS, you can register that handler now:

```bash
repolens install-protocol
repolens doctor
```

After that, RepoLens chat can attempt `Open in RepoLens Launcher` for suggested commands, and linked boards can resolve back to their local repo checkout.

## Release

This package is published from the repo via the `CLI Release` GitHub Actions workflow.
Before publishing, maintainers can run:

```bash
pnpm cli:smoke
```

## Common Commands

```bash
repolens whoami
repolens boards
repolens link --board-id <board-id>
repolens extract --depth standard
repolens plan --depth deep --supervisor codex
repolens graph query --kind runs --json
repolens graph query --kind relations --type exposes_endpoint --json
repolens map --output .repolens/repo-map.md
repolens analyze --depth deep --supervisor codex --verifier claude --publish-board-id <board-id>
repolens deep-analyze --supervisor codex --verifier claude --publish-board-id <board-id>
repolens context --base origin/main --head HEAD --output .repolens/context.md
repolens evolution --path src/lib/auth.ts --since origin/main --output .repolens/evolution.md
repolens hotspots --since origin/main --output .repolens/hotspots.md
repolens ownership --path src/lib/auth.ts --since origin/main --output .repolens/ownership.md
repolens start-here --path src/features/billing --since origin/main --output .repolens/start-here.md
repolens trace --query auth --since origin/main --output .repolens/trace.md
repolens trace --query BillingService --since origin/main --publish-board-id <board-id>
repolens run codex --task "Explain this change" --mode change-brief --base origin/main --head HEAD
```

`extract` builds the local evidence graph without invoking agents and now records deterministic manifests, configs, env keys, docs, endpoints, internal imports, external dependencies, and source symbols, `plan` generates an adaptive planning artifact from that stored graph, `map` proposes subsystem paths for large repos, `analyze` / `deep-analyze` run a supervisor-led full-analysis workflow for large codebases, `graph query` inspects the local SQLite-backed analysis store under `.repolens/analysis.db`, `evolution` and `ownership` surface rename / move history when git can resolve it, directory targets produce subsystem summaries, `start-here` builds reading order plus commit themes and why-changed context, `trace` recognizes exact symbols and likely definitions, and all six history commands can publish directly into a linked board with `--publish-board-id`.