Command 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):

Then install Nehemvix in its own environment, from PyPI:

pipx install aelsha-nehemvix
nehemvix --version

Update with pipx upgrade aelsha-nehemvix; remove it with pipx uninstall aelsha-nehemvix.

Check that your machine has what a run needs:

nehemvix doctor

It checks Python, git (2.50.1 or newer), Graphviz and PDF export, and lists which key variables are set. It ends with ready (exit code 0) or names what is missing (exit code 1).

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=...
nehemvix 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. Before that, it prints the estimate, for example estimate: $0.018 to $0.038 (likely $0.024), about 19 model calls, about 2 min, and when it stops it says which --cap is enough.

What you get

Everything is written to ./out (--out to change it), named after the repository:

Progress, checkpoints and remembered file summaries live in ~/.nehemvix (--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.

With --json, the same outcome is in the result's status and exit_code, and next_action says what to do (schema).

For AI agents and scripts

Add --json to run, resume, finish, ask or doctor: stdout then carries exactly one JSON object, valid against the JSON Schema, even when the input is wrong, and every human message goes to stderr.

nehemvix run https://github.com/pallets/itsdangerous --provider openai --model gpt-6-luna --cap 0.50 --json

• --events jsonl (with run, resume and finish) streams progress on stderr, one JSON object per line.
• run --estimate-only --json fetches the repository, prints the estimate and stops; nothing is spent.
• nehemvix list, status, outline, section, search and readiness read the guides in --data, for people or, with --json, for programs.
• nehemvix mcp serves those guides to an AI agent as a local MCP server over stdio.

Frameworks, the tools and the spending rules: Use Nehemvix from AI agents.

Every provider

Keys and credentials: Set up your AI provider.

Private repositories

Give a read-only access token in a variable you name; it is used for one fetch at the pinned commit and never stored:

export GIT_TOKEN=...   # GitHub: a fine-grained token with read access to the repository's contents
nehemvix run https://github.com/your-org/your-repo --provider openai --model gpt-6-luna --git-token-env GIT_TOKEN

GitHub, GitLab and Bitbucket need no user name; for another host add --git-user NAME. The job is marked private: its file summaries are never shared with other jobs' memory, and dependency lookups on public registries are off.

Ask a question

Ask about a finished guide; the answer comes from the guide's own index, written by the model you choose, with its sources and any names it couldn't find in the code:

nehemvix ask <job-id> "How are signed values given a timestamp?" --provider openai --model gpt-6-luna

In our test, questions about pallets/itsdangerous cost $0.0003 on gpt-6-luna and $0.0009 on claude-haiku-5-5.

Options

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:

nehemvix 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; if it has missing sections, it says so and points to nehemvix finish.

Finish the missing sections

When a guide finished with sections unwritten (the cap ran out while writing, or the model declined a section), write only those, on the same or any other provider:

nehemvix finish <job-id> --provider anthropic --model claude-sonnet-5-5 --cap 3.50

It lists the missing sections and prints the estimate next to what was already spent. --cap is for the whole job, so it must cover what was spent plus the most this finish can cost; without it, the job's own cap applies. When the cap is too low it stops before spending and says which cap is enough (exit code 1). Nothing finished is read or paid for again: in our test, a guide that stopped at its $2.00 cap with 9 sections missing was finished on Claude Sonnet with 15 calls (9 sections, 6 corrections) for $0.59, and its architect guide went from a grounding score of 52 to 99. The guides are written to --out again. Exit codes: 0 every section written (or nothing to finish), 1 stopped before spending or sections still missing, 2 no such job or a job that isn't finished (use resume), 3 a model's limit ran out (finish again later or on another model). With --json, a stop before spending is 4 (needs_approval, with the needed_cap_usd that would do), and a limit that ran out is paused with next_action finish.

How a run works: stages, checkpoints and state

A run is one LangGraph workflow, the same one the web app runs. The stages, in order:

1. ingest fetches the repository at a pinned commit (no checkout), removes secrets and flags text aimed at AI tools, all before any model call.
2. estimate computes the cost range and the number of model calls, then pauses for approval (see below).
3. agents runs the optional add-on agents that are enabled, if any, once the estimate is approved.
4. map summarises files in parallel batches. A gate after the batches routes back to re-plan only the files still unfinished if a model's limit stopped some of them.
5. reduce summarises folders from those file summaries.
6. synthesize plans the sections each audience gets.
7. write writes the sections in parallel, with a gate afterwards that does the same for sections still unwritten.
8. assemble builds each guide, evaluate checks names, paths and citations in code and scores the grounding, index makes the guide searchable (for ask, search and nehemvix mcp), and publish finishes the job.

Where state lives. Everything is under --data (default ~/.nehemvix): the job database nehemvix.db, the workflow's checkpoints in checkpoints.db next to it, and the stored guides in objects/. The guides you asked for are copied to --out.

Finished work is never redone or billed twice. Every paid unit (a file summary, a folder summary, a written section) is saved in the job_units table of that database under a stable key when it completes, and the call ledger records each model call's cost. On resume, after a Ctrl-C, or on another model, a stage first reads those units and only calls the model for what is missing. Switching provider or model therefore costs only the remaining work, and the stored units are reused whichever model made them.

Approval. The workflow stops at the estimate until someone approves it. In the web app that is a button. On the command line there is no approve flag: the --cap is the approval. If the estimate's upper end is within --cap, the run continues on its own; if not, it stops before spending anything (exit code 1, or 4 with --json). With --json --estimate-only it always stops there, so you can read the estimate and decide.

Quota pauses. When a model's daily or per-minute limit runs out or its key is refused, in-flight units finish or are deferred, nothing is lost, and the job is marked paused (exit code 3). It prints the files and sections done, the amount spent, and the command to continue. Wait for the limit to reset and run nehemvix resume <job-id> again, or continue now on another provider or model with --provider, --model and --key-env; the gates re-plan only the unfinished work, sized for the new model. Use the same --data folder.

Finishing a done guide. A job that ended with sections unwritten is not resumed: nehemvix finish estimates and writes only those sections, again on any provider or model, and refuses to start if the job's cap can't cover the worst case.

For the design behind this, see How it works, the architecture and pause and resume an agentic AI pipeline.

Common messages

To use Nehemvix in CI, Docker or your docs site, see Integrations.