CLI quickstart

The lupe CLI (@gigadrive/lupe, bin name lupe) reviews changes on your machine and prints the findings to your terminal. It reads the same review engine used by the GitHub Action, so you can catch issues before you ever open a pull request.

Running the CLI

Once lupe is installed as a package, you invoke it as lupe:

lupe review --print

In this monorepo the lupe bin is not globally linked, so during local development you run the built entry point with Node instead:

node apps/cli/dist/index.mjs review --print

The examples below use the lupe form. Substitute node apps/cli/dist/index.mjs if you are working inside the repo.

1. Set your provider key

lupe is bring-your-own-token: you point it at your own model provider and supply the key through an environment variable. For Anthropic:

export ANTHROPIC_API_KEY=sk-ant-...

Each provider reads its own conventional variable:

The claude-cli and codex-cli backends are opt-in and reuse your existing local Claude Code / Codex login instead of a key. See providers and models for the full list.

2. lupe check — validate config and credentials

Before your first review, confirm that lupe can see your config and credentials:

lupe check

It reports the resolved provider, the active profile (defaults to chill), your models mapping if you set one, and whether the provider's key variable is set or missing. If the key is missing for a provider that needs one, it warns you to set it before running a review; otherwise it prints ✓ ready. For a local backend it reminds you that it uses your local login and to make sure you are logged in.

You can point check at another repository or override the provider:

lupe check -C ../other-repo --provider openai

3. lupe init — scaffold a config

lupe init interactively creates a .lupe.yaml in the target directory. It asks which provider you will use and which review profile you want (chill or assertive), then writes a starter config with sensible path filters and a findings cap, and reminds you which key variable to export.

lupe init

See configuration for every key you can add to .lupe.yaml.

4. lupe review — review a diff

By default, lupe review reviews your working-tree changes and prints the findings:

lupe review --print

Use -C (alias for --cwd) to review a repository other than the current directory:

lupe review -C ../other-repo --print

Review a specific range

Pass --base and --head to review the diff between two refs instead of the working tree:

lupe review --base main --head HEAD --print

--base is the ref to diff against; --head defaults to HEAD.

Choose the output format

--format selects how findings are rendered. The default is md (human-readable markdown); sarif and json are machine-readable:

lupe review --format sarif --print

lupe review --format json --print

Other useful flags

Cost caps apply only to metered API providers — the local claude-cli / codex-cli backends are unmetered and report $0.0000 by design. See cost and budget for details.

5. lupe explain — review one file

To review just the changes to a single file, pass its path to explain:

lupe explain src/app.ts

explain accepts -C, --provider, and --format, and reviews only the changes to the given path.

Next steps

• CLI reference — every command, flag, and default.
• Configuration — the full .lupe.yaml schema.
• Providers and models — supported providers and how to pick models.