niro — MCP server + CLI (@niroai/niro)

The command-line tool and MCP server for Niro — the AI code-intelligence platform.

One package gives you three things:

1. niro CLI — onboard repos, build the code graph, and manage projects from the terminal.
2. A Niro MCP server — lets an AI assistant answer questions about your codebase using Niro's graph. 14 clients supported (Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, GitHub Copilot CLI, Factory, Goose, OpenCode, Cline, Kiro, Antigravity, Claude Desktop) — see docs/connect-your-ai-assistant.md for the exact command per client.
3. Two agent skills (installed by niro mcp install) so you can drive Niro from chat in plain English instead of typing CLI commands:
   • niro-skill — answers questions about your code (structure, call chains, blast radius) using the Niro MCP tools.
   • niro-cli — runs the CLI for you (onboard, status, rebuild, edit env vars, remove) from a conversation.

Two ways to do everything: every task below shows the terminal command and how you'd ask the agent. Pick whichever you prefer — they call the same code.

Working on branches

Your projects cover the repos and branches you chose to index. On every question, Niro routes to the project matching your repo and current branch. When you are on a branch no project covers (with real changes), Niro refuses to answer from stale code. Your assistant offers the fix:

niro new-temp-project     # run once in the repo folder

This creates your own private copy of the project that follows your branch and your uncommitted edits, live (keep niro watch running). Your original project is not changed. Switching branches needs nothing: Niro answers from your copy on the new branch, and from the matching indexed project on branches you already cover. When your branch is merged:

niro discard-temp-project

If you forget, idle copies are cleaned up automatically after two weeks. Full guide: docs/working-on-branches.md (plain-text file, ships inside the package too).

Install

npm install -g @niroai/niro
niro --version

Requires Node.js 18+. Background auto-sync of local folders uses PM2 — niro init offers to install it for you (or run npm install -g pm2 yourself).

By default the CLI talks to Niro's cloud (https://aiorchestrator.niroai.dev) and the MCP server to https://aiassistant.niroai.dev. To point at your own instance, set NIRO_API_URL, and pass --url <url> to niro mcp install (or set NIRO_MCP_SERVER_URL).

60-second setup

niro login            # opens your browser to approve this device
cd ~/code/my-service
niro init             # onboard this folder: create project, upload, build the graph
niro mcp install      # connect one AI assistant — pick it at the prompt, or pass --client

niro mcp install configures one assistant per run — pick it at the prompt, or pass --client <id>. 14 clients supported; see docs/connect-your-ai-assistant.md for the full list and the exact command for each. Run it once for each assistant you use. The MCP server URL is picked automatically (own instance? pass --url <url>). Restart your AI assistant once after, and you're done — ask it about your code, or ask it to run Niro tasks for you.

Scenario 1 — Log in

niro login opens a browser, you approve the device, and a long-lived credential is stored at ~/.niro/credentials.json (mode 0600). Short-lived tokens refresh automatically.

Terminal

niro login                              # browser device flow (default)
niro whoami                             # who am I logged in as?
niro logout                             # revoke + remove local credentials

Ask the agent

"Am I logged in to Niro?" — the agent runs niro whoami. If you're not, it will ask you to run niro login yourself in your terminal (it can't drive a browser sign-in or handle your credentials).

Scenario 2 — Onboard a folder you're working in

niro init does the whole thing end-to-end: detect the repo, upload its source + config files, create a Niro project, scan for environment variables, build the graph, and (optionally) keep it synced.

Terminal

cd ~/code/my-service
niro init                       # onboard the current folder
niro init ./api                 # onboard a specific path
niro init --defaults            # accept discovered defaults, don't prompt
niro init -X '**/test/**' -F '**/*.spec.ts'   # exclude modules / files

During init you'll be asked, per environment variable, which value to use — and when a variable is defined in more than one config file you pick which file drives it (see Scenario 6).

Ask the agent

"Onboard this folder into Niro." The niro-cli skill checks auth, runs niro info to see if it's already indexed, then runs niro init for you and walks you through the env-var values in chat.

Note for cloud: Niro indexes your folder by uploading its files (it can't read your laptop's disk). Source and committed config files (package.json, pom.xml, application.yml, …) are uploaded; anything your repo .gitignores (like a real .env) is never uploaded. One caveat: that filtering needs the folder to be a git repository. If you onboard a plain folder that is not a git repository, there is no .gitignore to honour and only the filename rules apply, so keep secrets out of it.

What can be onboarded: the folder has to look like a project — a build file (package.json, pom.xml, go.mod, *.csproj, …) at the folder itself or just below it. A monorepo root whose build files sit one or two levels down is fine. A folder with no build file is refused; pass --force if you really mean it. Your home folder, the filesystem root and system folders are refused outright, and --force does not override that — onboarding one of those would upload source from every project on the machine.

Scenario 3 — "What does Niro know about this folder?"

Terminal

niro info                # repo URL, branch, which project(s) map here, index status
niro info --json         # machine-readable
niro status              # live build status for the pinned project
niro status my-service --json

If a folder maps to more than one project, info lists them and (in the terminal) build/edit/remove ask you to pick one.

Ask the agent

"What does Niro know about this folder?" / "Is this repo indexed?" — the agent runs niro info --json and explains it.

Scenario 4 — See all your projects

Terminal

niro projects            # account-wide list (alias: `niro ls`)
niro projects --json

Ask the agent

"List my Niro projects." — runs niro projects --json.

Scenario 5 — Rebuild the index after changes

Terminal

niro build               # full rebuild of the project pinned to this folder
niro build my-service    # by alias or id
niro build --no-full-rebuild   # incremental
niro build --no-watch          # trigger and return immediately

Ask the agent

"Rebuild the Niro index for this project." — runs niro build.

(If you set up auto-sync in Scenario 8, you rarely need to rebuild by hand.)

Scenario 6 — Manage environment variables (and pick which file drives each)

Niro discovers env-var names from your code and their default values from committed config files. When the same variable appears in several files (e.g. application.yml vs application-prod.yml), you choose which file's value to use — the same as the web UI.

Terminal

niro edit --list-env                       # show vars, which file drives each, "appears in N files"
niro edit --list-env --json                # machine-readable (secret values masked)
niro edit --set-env PORT=9000              # set a value directly (never printed back)
niro edit --set-env-from PORT=application-prod.yml   # adopt that file's value for PORT
niro edit --rescan-env                     # re-scan after adding config files

Secret values are always masked (****) — whether the variable name looks secret (DB_PASSWORD) or its value embeds credentials (DATABASE_URL=postgres://user:pass@host). You pick those by file name; the value is never shown.

Ask the agent

"Set PORT from application-prod.yml" or "What env vars does this project have?" — the agent runs niro edit --list-env --json, shows you the choices, and applies your pick with --set-env-from. It chooses by file name and never handles raw secret values.

Scenario 7 — Rename a project, or add/remove a repo

Terminal

niro edit --alias new-name                 # rename the project
niro edit --add-repo <gitId>               # map a registered repo into the project
niro edit --remove-repo <gitId>            # unmap a repo (non-destructive)
niro edit --project my-service --alias renamed   # target a project explicitly

Ask the agent

"Rename this Niro project to payments-api." / "Remove repo X from this project."

Scenario 8 — Keep a local folder auto-synced

niro init and niro add repo install a background daemon (via PM2) that re-uploads your changes and keeps the graph fresh — honoring .gitignore so secrets never leave your machine.

Terminal

niro service install     # install + start the niro-watch daemon (auto-starts on login)
niro service status
niro service uninstall
niro watch               # run a watch in the foreground (debugging / no PM2)

Scenario 9 — Remove a project or detach a repo

Terminal

niro remove --unmap-repo <gitId>                         # detach one repo (non-destructive)
niro remove --project --confirm-name my-service          # delete the WHOLE project (guarded)

--project is destructive, so it requires --confirm-name to exactly match the project's alias or id.

Ask the agent

"Remove the Niro project my-service." — the agent confirms with you, then runs niro remove --project --confirm-name my-service.

Scenario 10 — Ask your AI assistant about your code

After niro mcp install (and a restart of your assistant), the niro-skill routes code questions through Niro's graph instead of grep:

"What calls chargeCard()?" "What breaks if I change the Invoice schema?" "Where is the auth middleware wired up?" "Is there existing code that parses webhooks before I write a new one?"

This works in any folder that resolves to a Niro project (via its git remote or a .niro-project pin).

Where does the MCP point?

"Which backend is my Niro MCP connected to?" — the niro-cli skill inspects your editor's MCP config and reports the URL + connection status.

Scenario 11 — Disconnect an AI assistant (uninstall the MCP)

niro mcp uninstall is the exact inverse of niro mcp install: it removes the MCP server registration and everything install added for that editor — the niro hooks in ~/.claude/settings.json, the ## Niro MCP section in CLAUDE.md / AGENTS.md, the generated niro-skill / niro-cli skills, and Cursor's allowlist entry + project rule. It only touches niro's own entries; your other hooks, MCP servers, and notes are left intact.

Terminal

niro mcp uninstall                      # interactive: pick client(s) (or "all")
niro mcp uninstall --client claude-code # remove from one editor, no prompt
niro mcp uninstall --client claude-code,codex  # remove from several in one go
niro mcp uninstall --all -y             # remove from every editor, skip the confirm

It does not sign you out — your niro login session in ~/.niro/credentials.json is kept (run niro logout to clear it), and the niro command itself stays installed (remove it with npm rm -g @niroai/niro). The shared ~/.agents/skills (used by both Codex and Windsurf) is only deleted once the last of those two editors is disconnected, so uninstalling one never breaks the other.

Ask the agent

"Disconnect Niro from Claude Code." / "Uninstall the Niro MCP from all my editors."

Command reference

| Command | What it does | |---|---| | niro login / logout / whoami | Authenticate / sign out / show current account | | niro init [path] | Onboard a folder end-to-end (upload, project, env scan, build, watch) | | niro info [path] | What Niro knows about this folder (repo, branch, project(s), status) | | niro projects (niro ls) | List all projects in your account | | niro status [project] | Live build status for a project | | niro build [project] | Trigger a rebuild and stream progress | | niro edit … | Rename, map/unmap repos, manage env vars (incl. --set-env-from) | | niro remove … | Delete a project (--project, guarded) or detach a repo (--unmap-repo) | | niro add repo [path\|url] | Register a local folder or remote git URL | | niro add project | Create a project from registered repos | | niro watch [path] / niro service … | Foreground watch / manage the auto-sync daemon | | niro mcp install | Connect an AI assistant + install the agent skills (one per run; --client <id> to skip the prompt, --url <url> for your own backend) | | niro mcp uninstall | Disconnect an AI assistant — reverses mcp install (--client <id> / --all, -y to skip confirm) | | niro delete [project] | Older whole-project delete (prefer niro remove --project) |

Add --json to whoami, info, status, projects, build, and edit --list-env for machine-readable output. Add --help to any command for its full flags.

Config & local state

| Location | Purpose | |---|---| | ~/.niro/credentials.json | Auth credential + token (mode 0600) | | ~/.niro/config.json | apiUrl / mcpServerUrl saved during setup | | ~/.niro/projects.json | Per-folder sync state (gitId, patterns, file hashes) | | .niro-project (in a repo) | Pins that folder to a Niro project (single line: project id or alias) |

| Environment variable | Purpose | Default | |---|---|---| | NIRO_API_URL | CLI → ai-orchestrator base URL | https://aiorchestrator.niroai.dev | | NIRO_MCP_SERVER_URL | MCP server (ai-assistant) base URL | https://aiassistant.niroai.dev | | NIRO_API_KEY | Read by the MCP server (e.g. headless niro mcp serve) — not a CLI-command auth path; for CI use niro login --api-key | — | | NIRO_UPLOAD_CONCURRENCY / NIRO_UPLOAD_TIMEOUT_MS / NIRO_UPLOAD_MAX_TOTAL_BYTES / NIRO_UPLOAD_MAX_FILES | Tune the initial upload | 4 / 60000 / 1 GiB / 50000 |

Security notes

• Secrets stay on your machine. Uploads honor .gitignore (and .git/info/exclude / global excludes), so a gitignored .env is never sent. Raw .env/*.properties files aren't in the upload set; committed config files (application.yml, .env.example, …) are, because they hold behavioral defaults, not secrets.
• Secret values are never printed. --set-env / --set-env-from never echo a value, and --list-env masks any value that looks like a secret — by key name or by content (connection strings, keys).
• The agent never handles raw secret values. It picks env sources by file name; you type any real secret yourself.

Troubleshooting

• The agent doesn't run Niro commands — restart your AI assistant after niro mcp install (skills load at startup). Re-running niro mcp install refreshes the skills if they've been updated.
• niro not found — ensure your global npm bin is on PATH (npm bin -g).
• A folder maps to multiple projects — pass --project <alias|id> (or pick one when prompted).
• Auto-sync isn't running — install PM2 (npm install -g pm2) then niro service install.

License

MIT