Ninoo Code

CLI reference

New here? Start with Download and install and How it works.

Install & sign in

$ curl -fsSL https://ninoo.ai/install.sh | sh

Command	What it does
ninoo login	Opens nicrron.ai to authorize this device; the minted key is saved to ~/.ninoo/config.json and never passes through the browser.
ninoo logout	Removes the stored key from this machine. Revoke it fully from the Nicrron dashboard's API Keys page.
ninoo update	Installs the latest version. Ninoo checks once a day and shows a notice when one is out; it never updates itself without you.

Usage

Shell

ninoo                          # interactive session in the current directory
ninoo "fix the failing test"   # one task, then exit (scripts and pipes OK)
ninoo -m nicrron/coding        # start with a specific model or mode
ninoo --mode plan              # research and plan first, change nothing
ninoo -y "run the linter and fix what it finds"   # auto mode: risky steps still ask

Flag	Meaning
-m, --model <slug>	Model or routing mode for this run (default: nicrron/builder).
--base-url <url>	Gateway URL (default: https://api.nicrron.ai).
--mode <mode>	Start in manual (default), accept-edits, plan or auto. See Permission modes.
-y, --yes	Same as --mode auto. Routine work runs unasked; deletes, pushes, deploys, secrets and anything outside the folder still ask.
-h, --help	Print usage.

Slash commands

Type / for a live-filtering dropdown. ↑ ↓ move, tab completes, ↵ runs.

Command	What it does
/model [slug]	Opens the model picker (modes first, then the live catalog with prices), or switches directly with a slug. The choice is saved.
/init	Explores the repo and writes NINOO.md project notes, or improves an existing one. Confirmations and /undo apply.
/undo	Reverts the last turn's file changes from the per-turn snapshot and tells the model.
/compact	Replaces the history with a short summary to reclaim context.
/clear	Clears the conversation history.
/status	Model, mode, gateway, cwd and the session's token totals.
/mode [name]	Shows or sets the permission mode: manual, accept-edits, plan, auto.
/permissions	The mode, your allow/ask/deny rules, and what auto mode recently approved or blocked.
/help	Lists commands, modes and shortcuts.
/exit	Quits. Plain exit or quit work too.

Keyboard

Keys	Action
shift+tab	Cycle permission modes: manual → accept edits → plan → auto. Works mid-turn.
esc	Interrupt the running turn; the half-finished step is discarded.
(just type)	Keep typing while Ninoo works; messages queue and run in order.
↑ / ↓	Walk your prompt history (~/.ninoo/history).
ctrl+a / ctrl+e	Jump to start or end of line.
ctrl+u / ctrl+k	Delete to start or end of line.
ctrl+w	Delete the previous word.
paste	Multi-line pastes are one block (bracketed paste).

Permission modes

Press shift+tab to switch. The footer under the input box shows the current mode.

Mode	What runs without asking
manual	Reading and searching. Every edit, command and fetch asks first. The default.
accept edits	Also file edits and simple file commands (mkdir, mv, cp) inside the project. Other commands ask.
plan	Read-only. Ninoo researches and proposes a plan; nothing changes. When it finishes you choose: implement in auto mode, accept edits, ask each time, or keep planning.
auto	Routine work: edits, file commands, reads, docs fetches. Builds, tests and unfamiliar commands get a quick check by a small safety model (openai/gpt-6-luna) that sees only your requests and the command, never file contents.

Some things always ask, in every mode, and no rule or model can approve them for you:

Always asks	Examples
Deleting	rm -r, rm -f, wildcards, find -delete, xargs rm, git clean
Losing or publishing git work	push --force, pushing to main or another branch, reset --hard, checkout -- ., rebase, branch -D
Root and remote code	sudo, curl … \| sh, base64 -d \| sh
Deploys and shared systems	terraform apply, kubectl delete, aws/gcloud changes, vercel --prod, npm publish, database migrations, DROP / DELETE without WHERE
Secrets	reading .env, keys and credential files; printing env vars or tokens. After a secret is read, every network action asks for the rest of the session.
Outside the project	edits outside the folder, shell startup files, ~/.ssh, ~/.aws, .git internals, CI workflows, .ninoo hooks
Changed scripts	running package.json scripts, a Makefile or a script the agent edited this session

Ninoo reads every command the way the shell would, through &&, pipes, $(…), bash -c, sudo, xargs, find -exec and npm scripts, so a risky step can't hide inside a harmless one. Catastrophic commands like rm -rf ~ get a red warning with No preselected. If auto mode is refused 3 times in a row it pauses and asks for everything until the turn ends. Without a terminal, anything that needs you is refused. Every decision is logged to ~/.ninoo/audit.log.

Add your own rules under permissions in ~/.ninoo/config.json. Deny beats ask, ask beats allow, and allow never overrides the always-ask list. A repo's .ninoo/permissions.json can add ask and deny rules but not allow rules, so a cloned project can't pre-approve its own commands.

Routing modes

Virtual slugs the gateway resolves at request time. Use them anywhere a model slug is accepted.

Mode	Routing
nicrron/builder	GPT-6 Luna, with GPT-5.4 mini and Claude Sonnet 5.5 as fallbacks. Same as the Builder. The default.
nicrron/auto	Right-sizes the model per request.
nicrron/coding	Strongest coding models first, with cheaper fallbacks.
nicrron/reasoning	Deep-reasoning models for hard problems.
nicrron/fastest	Lowest-latency lightweight models.
nicrron/cheapest	Cheapest model per token; quality varies.

Project memory (NINOO.md)

At startup Ninoo loads two Markdown files into its context, personal notes first, then the project's. Edit or prune them by hand anytime.

File	Scope
~/.ninoo/NINOO.md	Personal notes that apply everywhere: preferences, common commands.
./NINOO.md	This repo's build and test commands, conventions and gotchas. Created by /init, extended by the remember tool with approval. Commit it.

Configuration

Everything lives in ~/.ninoo/config.json with owner-only permissions. Environment variables override the file; the file overrides defaults.

~/.ninoo/config.json

{
  "apiKey": "sk-af-…",              // from ninoo login
  "baseUrl": "https://api.nicrron.ai",
  "webUrl": "https://nicrron.ai",
  "model": "nicrron/builder",       // saved by /model
  "safetyModel": "openai/gpt-6-luna", // auto mode's safety check
  "permissions": {
    "allow": ["bash(npm run test*)", "fetch(domain:docs.python.org)"],
    "ask":   ["write(src/payments/**)"],
    "deny":  ["bash(git push*)"]
  }
}

Env var	Overrides
NINOO_API_KEY	The stored key. Useful in CI without a login.
NINOO_BASE_URL	Gateway URL.
NINOO_WEB_URL	The web app used by ninoo login.
NINOO_MODEL	Model or mode.
NINOO_SAFETY_MODEL	The auto-mode safety check model.
NINOO_NO_UPDATE_CHECK	Set to 1 to turn off the daily update check.

Troubleshooting

Message	Fix
Not logged in	Run ninoo login.
Invalid API key	The key was revoked or rotated. Run ninoo login again.
Out of credits	Top up at nicrron.ai/dashboard/credits and rerun; the session's history is preserved.
command not found: ninoo	Add export PATH="$HOME/.local/bin:$PATH" to your shell profile.
ninoo update: unknown command	You have a version from before updates existed. Re-run the install command once; after that ninoo update works.
Could not load the catalog	The gateway was unreachable when /model opened; the nicrron/* modes are still offered. Check your network or --base-url.

Still stuck? Email support@nicrron.ai.