NaN CLI.

NaN has an official terminal tool, helmcode/nan-cli. It does two things: it shows you your real usage, and it configures your coding tools for you, without you having to edit configuration files by hand.

It is a shortcut, not a requirement. Everything it does can be done by hand by following your tool’s page in this same section.

What it configures on its own

Tool	Automatic setup
OpenCode	Yes
Codex	Yes
Pi	Yes
Factory AI (`droid`)	Yes
Hermes	Yes

Claude Code, Cursor, VS Code, Cline and Zed still need the manual configuration from their pages.

It only lists tools you actually have installed, and it only touches the NaN part of each file: everything else in them is left as it was, and unticking a tool takes ours back out again. Hermes is the exception to “writes the file”: the CLI drives hermes config set, which is Hermes’ own way of writing its config, so the comments in it survive.

The key you paste is checked against the cluster before anything is written, so a mistyped one is caught there instead of turning up later as a 401 inside each tool.

What else you get

The CLI opens a panel with tabs you move through with the arrow keys:

Tab	What for
Home	The keys, and what each tab is for
Profile	Your account details
Usage	Tokens spent over 24 hours, 30 days and all time
Models	The models available and how much you have spent on each
Costs	What the same thing would have cost you at other providers
Setup	Your API key and the automatic setup of tools
About	Version and links

The Usage tab is the fastest way to know how much quota you have left before starting a long agent session.

Installation

Install the binary

On macOS and Linux, one line:

curl -fsSL https://nan.builders/install | bash

The installer looks at your system and architecture, downloads the right binary from the latest published release, verifies its checksum and puts it in /usr/local/bin/nan. If that directory needs administrator rights, it will ask for your password through sudo.

To put it somewhere else, give it the directory yourself:

INSTALL_DIR="$HOME/.local/bin" curl -fsSL https://nan.builders/install | bash

If the directory you choose is not in your PATH, the installer says so and hands you the line to add to your ~/.zshrc or your ~/.bashrc.

On Windows, from PowerShell:

irm https://nan.builders/install.ps1 | iex

It does the same work: resolves the latest release, downloads the .zip for your architecture, verifies its checksum and puts nan.exe in %LOCALAPPDATA%\Programs an, adding that directory to your user PATH if it is not there already. Terminals you already had open will not see it until you restart them.

It installs for your user and not for the whole machine, deliberately: the Windows equivalent of the sudo prompt is an elevation dialog out of a piped script, which is worse. To put it elsewhere:

& ([scriptblock]::Create((irm https://nan.builders/install.ps1))) -InstallDir "C:	ools"

There are binaries for macOS, Linux and Windows, on Intel and on ARM.

Check that it worked

nan --version

It has to answer with the version and the name of the tool. If your terminal says the command is not found, the binary is installed but its directory is not in your PATH.

Get your API key

At cloud.nan.builders, in your user settings, under API Keys.

Or let the CLI log you in

nan auth login --email you@yours sends you a sign-in link, the same one the platform uses. Copy it out of the email and paste it back into the command, without opening it in the browser first: it works once, and the browser would spend it. That gets you the Profile, Usage and Costs tabs. The Setup tab, which is the one that configures your tools, needs the API key and nothing else.

Before v0.1.2 this command pointed at a retired Discord endpoint and answered 404. If that is what you see, you are on an older build: curl -fsSL https://nan.builders/install | bash again.

Configure your tools

nan

Inside the panel, go to the Setup tab with the arrow keys. Press e and paste your API key. With space, mark the tools you want configured. Press c to apply.

The CLI writes the configuration for each tool you marked. Quit with q and start your agent:

opencode

Inside OpenCode, /models shows you the NaN models, already available.

Building from source

This is the path on Windows, and the one you want if you are going to work on the CLI itself. You need Go 1.26 or newer:

git clone https://github.com/helmcode/nan-cli
cd nan-cli
go build -o nan .

That leaves the binary in the repository directory. To have it at hand from anywhere, move it to a directory in your PATH:

mkdir -p ~/.local/bin
mv ./nan ~/.local/bin/nan

If that directory is not in your PATH yet, add it to your shell’s startup file. On macOS the default shell is zsh, so the file is ~/.zshrc and not ~/.bashrc:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

On Linux with bash, the same command but against ~/.bashrc.

Runs

From v0.1.25 the CLI also starts agents on tasks inside your workspaces, and follows them from your terminal:

nan run "add tests for the date parser and make them pass"
nan runs ls
nan runs logs <id> -f
nan run --byok-secret ANTHROPIC_KEY --model claude-sonnet-4-5 "fix the flaky test"   # v0.1.32+, your own provider key

The run happens in the workspace, not on your machine, so it keeps going if you close the terminal. The runs commands use your nan auth login session, or a platform token from NAN_TOKEN, --token-file or nan auth login --api-token for scripts, CI and servers. Every flag, the authentication order, the exit codes and the API are in Agent runs.

Automations

From v0.1.26 the CLI also lists and runs your automations, and shows the proposals waiting for your approval:

nan automations ls
nan automations run "PR review" --input '{"pr": 42}'
nan approvals ls
nan runs proposal <run-id>
nan runs reject <run-id>
nan secrets ls

From v0.1.33, where your account has the write API (it is being opened gradually), the CLI also creates and changes your secrets, automations and triggers:

nan secrets set GITHUB_TOKEN --value-file ./token.txt     # add it, or replace its value
gh auth token | nan secrets set GITHUB_READ_TOKEN --value-stdin
nan secrets show GITHUB_TOKEN
nan secrets edit GITHUB_TOKEN --description "repo acme/api"
nan secrets rm OLD_TOKEN
nan automations create -f automation.yaml
nan automations edit "PR review" -f changes.yaml
nan automations disable "PR review"
nan automations triggers add "PR review" -f webhook.yaml  # prints the URL and secret once

A secret’s value is read from a file or a pipe, never from the command line, and nothing ever prints it back. Every nan secrets flag, how to rotate a secret and the errors you can see are in Secrets. Until your account has the write API, these commands say so and point you to the portal. Approving proposals always happens in the portal, signed in through your browser.

From v0.1.34, where your account has notifications, nan notifications manages the channels that tell you in Slack, Microsoft Teams, Discord or your own endpoint when an automation needs your approval or fails: nan notifications add "team alerts" --kind slack --url-file ./slack-url.txt, then nan notifications test "team alerts". The webhook URL is read from a file or a pipe, never from the command line. Every command is in Notifications.

These commands use your nan auth login session first (it wins over NAN_TOKEN; --token-file wins over both), or a platform token with the scopes they need: secrets:read and secrets:write for secrets, automations:write (plus automations:read to use names) for automations; see Tokens for automations. Sign in on your own machine, never inside a workspace: the agents there could read the session and change your secrets. Every command, the YAML files and the warnings are in Manage them from the CLI or the API.

A run waiting for approval makes nan run, nan runs logs -f and nan automations run exit with code 10. The details are in Automations.

Updating

Run the installer again. It always brings the latest published release and overwrites the one you have:

curl -fsSL https://nan.builders/install | bash

To remove it, delete the binary: rm /usr/local/bin/nan, or whatever path you gave it with INSTALL_DIR. It leaves nothing else behind on your system.

If you would rather not install anything

That is perfectly reasonable. Go straight to your tool’s page and copy the configuration block:

The result is the same. The only thing you miss out on are the usage and cost tabs.

Known issues

On Windows you have to build. The published releases carry macOS and Linux binaries; for Windows, the path for now is go build.
The installer asks GitHub for the list of releases. If you are behind a proxy that blocks api.github.com, it will find nothing to download. In that case, grab the .tar.gz for your system by hand from the releases page.