NOVA CLI

Official CLI for Bridgeye NOVA.

Using NOVA day to day — permission modes, memory, skills, what the results mean and what to do when it stops: docs/USING-NOVA.md.

Bring a local instruction skill: docs/BRING-YOUR-OWN-SKILL.md.

Developer and coding-agent verification: canonical Nox checks.

Install

The recommended install brings its own Python, verifies every byte it downloads against the release's published checksums, and keeps itself up to date.

macOS and Linux

curl -LsSf https://nova.bridgeye.com/install.sh | sh

Windows (PowerShell)

irm https://nova.bridgeye.com/install.ps1 | iex

Then open a new terminal and run:

nova

The installer puts NOVA in your own user directory — no administrator rights are needed, and nothing outside that directory is modified except one entry added to your PATH.

With pip

If you would rather manage NOVA yourself, it is on PyPI. Python 3.10 or newer:

pip install nova-bridgeye

The distribution is nova-bridgeye. pip install bridgeye-nova is not NOVA and will fail — the two words are the wrong way round.

pipx install nova-bridgeye works too, and is the better choice if you want NOVA isolated from your other packages.

Git is optional

NOVA works without Git. Building, editing and \undo never need it. When you ask for something that does — \commit or \push — NOVA says Git is missing and offers to install it. You can also install it at any time:

nova setup-git

• Windows installs Git for Windows through winget.
• macOS installs Homebrew's Git when Homebrew is available. Without Homebrew, type git in Terminal and macOS offers to install it for you.
• Linux: NOVA prints the command for your distribution and installs nothing, because every one of them needs sudo.

Git is not installed silently by pip: operating-system software may require administrator approval, and declining it must not prevent NOVA from opening.

Repository intelligence

Nova automatically uses a local relationship index for architecture, impact, dependency, caller/callee, and cross-file tasks. You do not need to mention the indexing engine or run a special command before asking Nova to work. Exact source is still read and verified before Nova makes a claim or edit.

The engine is isolated from Nova's Python environment and code-only analysis is offline. Repository code is parsed, never imported or executed. If the engine is unavailable, Nova falls back to its existing symbol index, Grep, and Read tools without blocking the turn.

NOVA sets up the isolated engine and indexes the project in the background. nova intelligence status shows whether it is preparing, ready, or using regular search. Setup failures never block a turn.

Administrative commands are available when needed:

nova intelligence status
nova intelligence refresh
nova intelligence rebuild
nova intelligence export ./repo-intelligence
nova intelligence compare baseline.json graphify.json
nova intelligence on        # always use when relevant
nova intelligence off       # use local search only
nova intelligence clear --yes
nova doctor --repair-intelligence

Private artifacts live under <project>/.nova/graphify/ and are ignored by Git. Semantic document, image, and media extraction is disabled in this MVP; Nova never forwards repository content or ambient provider credentials through the repository-intelligence sidecar.

For an existing project, substantive build and change requests are Graphify-first even when the prompt does not say “architecture” or “refactor.” Nova skips the graph for a new empty project and clearly isolated work such as formatting one named file. Every turn records whether the map was used, skipped, or fell back to local search, together with freshness, selected file and relationship counts, graph revision, and the server-reported token charge.

The CLI closing line shows this proof. A token or credit saving is shown only when a matched Graphify-off baseline exists for the same work. Without that control, Nova says matched baseline required; it does not turn an estimate into a savings claim.

To create that proof without allowing either run to edit the project, run the same planning prompt against the same source revision and model:

nova intelligence off
nova -p "Plan how to add login; do not edit files" --permission-mode plan --output-format json > .nova/graphify-off.json
nova intelligence on
nova -p "Plan how to add login; do not edit files" --permission-mode plan --output-format json > .nova/graphify-on.json
nova intelligence compare .nova/graphify-off.json .nova/graphify-on.json

The comparison is rejected unless task, model, source fingerprint, Graphify decision, and server-reported charge all match the proof contract. The saved proof then appears in nova intelligence status, the CLI turn summary for the matching task. Credit savings appear only when both run records contain the same positive tokens_per_credit value supplied by the server. If that rate is absent, Nova reports saved charged tokens without inventing credits.

Updating

How you installed decides how you update, and NOVA tells you which applies on its launch screen.

Automatic updates are skipped on metered connections, in CI, and in non-interactive runs. Set NOVA_NO_AUTO_UPDATE=1 to turn them off entirely, or run nova update --now to fetch one on demand.

Removing NOVA

nova uninstall

Removes the managed installation — the versions directory, the current link, the launcher and NOVA's entry on your PATH — after showing you the list and asking. It keeps ~/.nova: your settings, history, saved memory and any skills you added. Your projects are never touched.

nova uninstall --purge deletes ~/.nova as well. It says so first and asks again; --yes answers only the ordinary question, never that one.

On Windows the last step finishes as NOVA exits, because the running nova.exe cannot delete itself while it is open. Open a new terminal afterwards.

Installed with pip, pipx or conda? nova uninstall will tell you the right command for that install rather than touching it.

Checking an install

nova --version
nova doctor

nova doctor reports the API endpoint, sign-in state, tool availability and loaded skills, and exits non-zero if something needs attention.

Uninstall

A curl/irm install lives entirely in one directory, named in receipt.json inside it. Delete that directory and remove its bin entry from your PATH.

A pip or pipx install is removed with pip uninstall nova-bridgeye or pipx uninstall nova-bridgeye.

Support

support@bridgeye.com