RepoLanternCommand line
The same pipeline as the web app, on your own machine, with your own key. Your spending limit is your approval.
Install
You need Python 3.12 or newer, git 2.50.1 or newer, Graphviz (diagrams) and Pango (PDF export):
| System | Command |
|---|---|
| macOS | brew install git graphviz pango pipx |
| Ubuntu | sudo add-apt-repository ppa:git-core/ppa, then sudo apt-get install git graphviz libpango-1.0-0 libpangoft2-1.0-0 pipx (Ubuntu's own git is older than 2.50.1) |
| Debian | sudo apt-get install graphviz libpango-1.0-0 libpangoft2-1.0-0 pipx, plus git 2.50.1 or newer (check git --version; Debian's own may be older) |
| Windows | Use WSL (Ubuntu) and follow the Ubuntu line |
Then install RepoLantern in its own environment, from PyPI:
pipx install aelsha-repolantern
repolantern --version
Update with pipx upgrade aelsha-repolantern; remove it with pipx uninstall aelsha-repolantern.
Your first guide
Put your key in an environment variable, never on the command line. By default each provider reads its usual
variable (GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, VERTEX_API_KEY, OPENAI_COMPATIBLE_API_KEY,
AZURE_AI_API_KEY, BEDROCK_API_KEY); --key-env names another.
export ANTHROPIC_API_KEY=...
repolantern run https://github.com/pallets/itsdangerous --provider anthropic --model claude-haiku-5-5 --cap 0.50
It prints a job id, the estimate, then one line per step while it reads the code and writes the guide, and ends with the grounding score and the cost. In our tests this repository (46 files) took about three minutes and $0.06 on claude-haiku-5-5, and the three guides for a one-file repository cost $0.01 on gpt-6-luna.
On the command line there is no approve button: the run continues only if the estimate's upper end is within
--cap. Otherwise it stops before spending anything and says so; run again with a higher --cap, or give the
model's price with --price-in and --price-out (both) if it has no listed price.
What you get
Everything is written to ./out (--out to change it), named after the repository:
| File | What it holds |
|---|---|
owner_repo.beginner.md (and .senior.md, .architect.md) |
One guide per audience you asked for, in Markdown, with diagrams and citations to exact lines |
owner_repo.assessment.md |
The readiness checklist: CI, tests, logging, licences and more, each pass, warn or not applicable, with evidence. Automated signals, not an audit |
owner_repo.report.json |
Machine-readable: each guide's grounding score and checks, cost and tokens by stage, the estimate, the checklist |
Progress, checkpoints and remembered file summaries live in ~/.repolantern (--data). A second run on the same
repository reuses the summaries of files that haven't changed, so it costs less.
Exit codes
For scripts and CI, the exit code tells you what happened; the last line says why.
| Code | Meaning |
|---|---|
0 |
Done: the guides and the report are written |
1 |
Stopped or failed: the estimate was above --cap, the price is unknown, the repository couldn't be read, or the --out folder can't be written (checked before anything is spent) |
2 |
Wrong input: an invalid link, an unknown provider or audience, a missing key variable, an unknown job id |
3 |
Paused: a model's limit ran out or the key was refused. Nothing is lost; resume it |
130 |
Stopped with Ctrl-C. Nothing finished is lost; resume it |
Every provider
| Provider | Example |
|---|---|
| Gemini | --provider gemini --model gemini-3.8-flash (reads GEMINI_API_KEY) |
| Vertex AI | --provider vertex --location global --service-account-file key.json, or an API key in VERTEX_API_KEY |
| Claude | --provider anthropic --model claude-haiku-5-5 (reads ANTHROPIC_API_KEY) |
| OpenAI | --provider openai --model gpt-6-luna (reads OPENAI_API_KEY) |
| OpenAI-compatible | --provider openai_compatible --base-url https://openrouter.ai/api/v1 --model nvidia/nemotron-3.5-super-vl:free --key-env OPENROUTER_API_KEY ($0 on a free model) |
| AWS Bedrock | --provider bedrock --region us-east-1 --model us.amazon.nova-micro-v1:0 (reads a Bedrock API key from BEDROCK_API_KEY), or an access key pair with --aws-key-id-env MY_ID --aws-secret-env MY_SECRET |
| Microsoft Foundry | --provider foundry --base-url https://<resource>.openai.azure.com --model <deployment> --key-env AZURE_AI_API_KEY |
Keys and credentials: Set up your AI provider. The command line documents public repositories; for a private one, use the web app, which takes a read-only access token for one fetch.
Options
| Option | Meaning |
|---|---|
--skills beginner,senior,architect |
Which guides to write (default: beginner) |
--length concise |
Concise, standard or detailed sections |
--cap 1.00 |
Spending limit in US dollars for the whole job |
--preset gemini_free, --rpm, --rpd, --tpm |
Your model's limits. Presets: gemini_free, gemini_paid, vertex_project, openai_tier, anthropic_tier, bedrock_on_demand, foundry_deployment |
--thinking medium, --analysis-thinking none |
Thinking while writing, and while reading |
--temperature 0.2 |
0 to 1, where the model accepts it |
--price-in, --price-out |
Your price per million tokens, for a model without a listed price (give both) |
--fallback "" |
No fallback model on the same key |
--cache-policy same_model_only |
Reuse remembered file summaries only from the same model (default: from any model) |
--out, --data |
Where the guides go, and where progress and memory live |
--aws-session-env NAME |
Bedrock with temporary credentials: the variable holding the session token |
Pauses and resuming
If a model's limit runs out or the key is refused, the run pauses (exit code 3) and prints the job id and the
command to continue. Continue later, on the same or another provider:
repolantern resume <job-id> --provider openai --model gpt-6-luna --cap 0.50
Finished work is reused, never paid for twice: in our test, a job paused on a daily request limit with Claude finished
on gpt-6-luna with a grounding score of 100. Stopping a run with Ctrl-C works the same way: resume it by its job id.
Use the same --data folder you ran it with. Resuming a job that already finished changes nothing.
Common messages
| Message | What to do |
|---|---|
error: set OPENAI_API_KEY in the environment, or name another with --key-env |
Export the key variable, or name yours with --key-env |
error: only https URLs are allowed / error: expected https://host/owner/repo |
Use the repository's https:// link |
error: non-public address |
The link points to a private network address; RepoLantern only reads public hosts |
the repository was not found, or it is private and needs credentials |
Check the link; private repositories need the web app |
== stopped before spending: the estimate's upper end is above --cap … |
Raise --cap, or give --price-in and --price-out |
== paused: the provider rejected the credentials … |
Check the key, the model's access and billing, then repolantern resume |
To use RepoLantern in CI, Docker or your docs site, see Integrations.