Commands¶
Full CLI reference for NurCLI.
Usage¶
Global options¶
| Flag | Short | Description |
|---|---|---|
--model <MODEL> |
-m |
Model id for the active provider (default from config; browse with /model in the TUI) |
--cwd <DIR> |
Working directory | |
--yes |
-y |
Auto-approve tools (sets permission mode to auto) |
--mode <MODE> |
Permission mode: manual, plan, or auto |
|
--effort <LEVEL> |
Reasoning effort: low, medium, high, xhigh, max, ultracode (also minimal; aliases med, extra, ultra). See effort levels |
|
--max-turns <N> |
Max agent turns per prompt | |
--continuous |
Sovereign mode: loop headless turns toward the prompt (as a goal) until the model replies DONE, Ctrl+C, or --max-iters. Auto-approves tools (sandboxed). |
|
--max-iters <N> |
Continuous mode: stop after N iterations (0 = unlimited) |
|
--verbose |
-v |
Verbose tool logging (headless mode) |
--continue |
-c |
Continue the most recent session for this cwd |
--resume <ID> |
-r |
Resume a specific session id (full UUID or unique prefix) |
--version |
Print version | |
--help |
-h |
Print help |
Examples¶
nur # open interactive TUI
nur install # one-stop stack install (same as release EXE)
nur "fix the bug" # start with a prompt
nur "design from ref.mp4" # vision: auto-attach media
nur -c # continue last session
nur -r abc123 # resume session abc123
nur --mode plan "explain this" # plan: explore + shell, no edits/commits
nur --effort max "deep analysis" # strongest reasoning the route takes
nur --effort ultracode "port the CLI" # max effort + parallel subagents
nur --model gpt-5.5 "hello" # explicit model
nur run "add tests" -y # headless + auto-approve
Subcommands¶
nur run¶
Run a single agent turn headlessly. Prints the final answer to stdout.
| Arg / Flag | Description |
|---|---|
PROMPT |
Prompt text (required, multiple words joined) |
-y, --yes |
Auto-approve all tools |
--output-format text\|json\|stream-json |
What stdout carries (default text). json: nothing until the end, then one {"type":"result", ...} object. stream-json: one JSON object per line (layers, status, tool_start, tool_end, text, assistant) ending in that same result object. In both JSON formats every diagnostic goes to stderr, so stdout parses. |
Example:
nur run "write a hello world in Rust" -y
nur run "explain what this repo does" -v
nur run "run the tests and summarise" -y --output-format json | jq .result
Headless contract. nur run is built to be driven by scripts, CI and other agents:
- stdout is the answer. No terminal-title escapes are ever written by
run(the TUI writes them only when stdout is a terminal). Status lines appear on stdout only with-vin text mode; in the JSON formats they go to stderr or becomestatusevents. - Exit codes tell failures apart without scraping text:
0ok ·1unexpected error ·2configuration ·3authentication (no key, or the provider rejected it with 401/403) ·4provider (other HTTP errors, network) ·5budget or turn limit ·6the model declaredBLOCKED: <what it needs>(the answer is still printed) ·130cancelled.nur "<goal>" --continuoususes the same codes (5for--max-iters,6for a declared blocker). Also innur --help. - The result object (
json, and the last line ofstream-json):ok,exit_code,result(the answer, ornullon error),error,blocked(the text afterBLOCKED:),session_id,model,provider,tool_calls,duration_ms,usage(input_tokens,output_tokens,total_tokens,estimated_cost_usd) andlayers. - Layers line. Every headless run reports once which side layers are live and why not when they are not:
layers · typesafe: off (no key: ...) · headroom: active (inline compress). On stderr in text mode, alayersevent instream-json, thelayersfield of thejsonresult. The probe runs on a background thread, never in front of the first request. - Notices print once. A standing condition (the provider capability profile, for example) is said the first time, not before every request.
- Side-model spend is visible. Every row in
~/.nur/usage.jsonlcarriespurpose:chatfor the turn itself,compaction/compaction-remotefor summaries,fusionfor panel members,subagentfor child sessions.
nur jev¶
Local System One engines (see jev-local.md) - typed judgments on this machine with no API key:
nur jev status # endpoint, credential, bridge state, per-device support
nur jev probe # the same, as JSON
nur jev selftest # mapping checks incl. a served request (no model, no downloads)
nur jev start --backend mock # verdict | nimble | laya | mock
nur jev start --backend nimble --nimble-dir D:/models/nimble-model
nur jev use --port 8788 # point [typesafe] at the loopback bridge
nur jev stop # stop the recorded bridge (verifies the port is free)
nur jev use --hosted # back to api.typesafe.ai
nur jev eval --set <name> # replay a recorded judgment set (NUR_JEV_RECORD)
nur jev eval --set <dev> --reserved <heldout> --limit 20
Engine flags are forwarded to the bridge verbatim: --verdict-model <id|path>,
--nimble-dir <dir>, --laya-model <bundle>, --laya-max-tokens <n>,
--device cpu|cuda|mps.
nur auth¶
Manage the stored API key (~/.nur/auth.json).
For multi-provider sign-in (pick OpenAI, OpenRouter, Ollama, xAI, … + endpoint
and default model), use the TUI slash command /provider (/login is an
alias). Use /auth for the scrollable all-provider credential vault. See
Authentication. CLI nur auth login can paste a key, run
an official harness/browser sign-in, or import a vendor CLI session, and updates
the active provider/model when --provider is set.
nur auth login¶
Save an API key or official harness/browser session to ~/.nur/auth.json (and
the per-provider store). Also writes provider / base_url / model into
~/.nur/config.toml. On the Claude / ChatGPT / Gemini subscription routes the
flow first prints the client identity the provider will see
(the table).
| Flag | Description |
|---|---|
--provider <ID> |
Catalog id or alias (muse, zcode, dsh, chatgpt, opencode-go, …); a typo fails with a closest-match suggestion |
--browser |
Official browser / harness sign-in when the provider has one |
--import |
Deprecated shortcut for nur auth import --from <source> |
--key <KEY> |
API key (optional; prompts if omitted and no browser flow runs) |
--model <MODEL> |
Also set the default model; without it the login ends by asking which model to make the default |
--yes |
Accept the first catalog model without asking (for scripts) |
nur auth import¶
Copy an existing vendor CLI or OMP session into nur's own store. The source
maps to the catalog provider (claude → anthropic, codex / chatgpt →
openai, omp resolves its own provider), so there is nothing else to pick.
Imports copy a rotating refresh token: whichever tool refreshes second is
signed out, which is why this is an explicit step rather than the default.
nur auth import --from <codex|claude|grok|kimi|cursor|opencode|antigravity|droid|muse|dsh|zcode|cline|qwen|mmx|hf|nous|cmd|omp>
nur auth status¶
Show auth status. Never prints the full key.
nur auth logout¶
Remove the saved key from ~/.nur/auth.json.
nur auth logout
nur auth logout --revoke # local delete + best-effort revoke notes for az/aws/gcloud
nur sessions¶
List recent sessions from ~/.nur/sessions.
| Flag | Default | Description |
|---|---|---|
--limit |
20 |
Max rows to display (0 = all) |
Columns: ID · UPDATED · MSGS · TOKENS · COST · CWD.
takeover — cross-agent session migration¶
takeover (chagent engine, inspired by SirTenzin/chagent) imports a coding-agent session from another harness into NurCLI so it resumes like any native session. Supported sources: Claude Code, Codex, Cursor, and Grok Build.
Under the hood it reuses the bundled resume-session/session_reader.py to
normalise each foreign store into one JSON intermediate representation, then
writes a native session (messages + Responses input_items + replayable UI
cards). The imported transcript is treated as inert history — verify files,
branch, and tests before continuing.
There are exactly two session windows, and one key switches between them:
| Command | Purpose |
|---|---|
/sessions · /resume |
Native nur sessions. Press c to switch to the takeover window. |
/takeover · /hijack |
Migratable foreign sessions. ↵ imports & resumes. Press c to switch back. |
/takeover ls [agent] |
List migratable sessions (all agents, or just one) |
/takeover <agent> [id\|latest] |
Import that session and resume it |
Agents are claude · codex · cursor · grok. Imports are re-homed to the
current workspace, so tools stay sandboxed here regardless of where the session
came from.
Scope: both windows default to all workspaces; Tab narrows either
one to the current folder. This matters most for Claude Code, whose sessions are
stored per project directory (~/.claude/projects/<dir>/) — a folder-scoped
listing shows nothing outside that exact directory, so the takeover window asks
the reader for every workspace (session_reader.py … --all-cwds) and tags each
row instead.
Requires Python 3 on PATH (python3 / python / py -3) and the
resume-session reader provisioned under ~/.nur/skills (run /ecosystem if
missing). The reader is an engine, not a skill — it is never NL-activated.
nur usage¶
Show last known token usage and estimated cost. Displays paths to status and usage log files.
Dollar values on the TUI status line and here are list-price estimates (per-model rates from models.dev when available, else Meta fallback constants, else $0 for local providers). They are not provider invoices. Cached prompt tokens are priced at the catalog’s cache-read rate when known.
Opt out of the catalog fetch with NUR_PRICING_OFF=1. Cache lives at ~/.nur/cache/models-dev.json (24h TTL).
nur install¶
One-stop install — same job as the release EXE and npx nur-cli (minus downloading or compiling the binary): copy binary → PATH → prereqs (best-effort) → ecosystem ensure → browser stage → Orca hook → optional auth from env. No TUI until this finishes (or until you open nur afterward).
Double-clicking nur-windows-x86_64.exe from Releases runs this path automatically, then opens NurCLI. npx nur-cli downloads the prebuilt binary first and then runs this same path.
nur update¶
How you upgrade NurCLI. Pull latest source, rebuild release, reinstall binary + full stack.
nur update
# dry run — print local version, latest release, the asset picked for this
# platform, and the decision, then exit WITHOUT installing anything:
nur update --check
nur update --check is the way to confirm auto-update is wired correctly from a
shell. It also prints when the launch-time check last ran and what it decided
(read from ~/.nur/auto_update.json); nur doctor shows the same block.
| Step | Action |
|---|---|
| Source | Uses ~/laboratory/nur-cli or ~/Laboratory/nur-cli if present |
| Git | git pull --ff-only origin main |
| Build | cargo build --release |
| Binary | Installs to ~/.local/bin/nur |
| Stack | ecosystem ensure --force, browser setup, Orca hook |
| No checkout | Falls back to nur install (repair from the running binary) |
Afterward: nur --version · nur doctor.
Full paths and alternatives (npx nur-cli / one-liner / EXE / nur install): Setup → Update.
nur plugins¶
Marketplace plugins (install into ~/.nur/plugins, skills mirrored to ~/.nur/skills).
nur plugins # list catalog + install state
nur plugins list
nur plugins install <id> # e.g. superpowers, vercel, firecrawl, fable
nur plugins enable <id>
nur plugins disable <id>
nur plugins uninstall <id>
Skills as slash commands: every installed skill is also /skill-name (sticky session mode) or /skill-name <prompt> (one-shot turn). With [skills] auto_activate = true, natural-language activation works with no slash: think like fable, TDD this, debug systematically, site cli, HAR file, resume from Claude — see Ecosystem.
In the TUI, bare /plugins opens the full marketplace picker (provider-picker UX).
nur permissions¶
Show the allow/deny/ask rules in force in this directory, or decide whether this project's own rules may approve tool calls.
nur permissions # same as `nur permissions show`
nur permissions trust # apply this project's .nur/permissions.toml allow rules
nur permissions untrust # hold them again
A project's .nur/permissions.toml arrives with the repository, so its deny
and ask rules always apply but its allow rules stay off until you trust them.
Trust covers the list as it is now: if a later commit edits it, nur holds it
again and says so at startup (nur run prints the note to stderr).
nur skills¶
Project-local skills (a repo's own .nur/skills, .claude/skills,
.agents/skills) are inert until trusted, like project allow rules.
nur skills trust # approve this project's skills exactly as they stand now
nur skills untrust # hold them again
Trust records a digest of every project SKILL.md, so a git pull that edits
one holds the set again. The TUI equivalent is /skills trust.
nur doctor¶
Diagnose install, auth, config, ecosystem, and plugin marketplace readiness. This command is read-only: it never launches a package manager or changes the ecosystem marker.
Checks:
- Binary path and version
- Config file (model, effort, max_turns, budget caps)
- Auth status (key present, last 4 chars)
- Data home, status, usage, sessions paths
- Ecosystem readiness (Graphify, PLUR, Ruflo, browser, omp when present)
- Shell backend (Bash / PowerShell)
- Optional tools on PATH (rg, git, node, npm, uv, ffmpeg)
- Vision support (look, extract_frames)
- Binary SHA-256 integrity
See Troubleshooting for interpreting results.
nur ecosystem¶
Manage the Graphify / PLUR / Ruflo / browser / omp ecosystem.
nur ecosystem ensure¶
Install or repair Graphify, PLUR, Ruflo, skills, and related packs. The one-liner, release EXE, and nur install already run this in the foreground. On later TUI opens it also runs as background TTL repair when ecosystem_auto_ensure = true (default).
| Flag | Description |
|---|---|
--force, -f |
Force re-install even if marker is fresh |
nur ecosystem refresh-skills¶
Install this version's first-party skill pack (the signed nur-skills.zip
release asset, see Ecosystem) if it is not already in place,
then rebuild and persist global skill metadata, without installing packages or
resolving credentials. Existing complete metadata remains readable during
replacement. A pack that cannot be fetched is reported and the installed copy
is kept.
nur ecosystem status¶
Show the last recorded ecosystem readiness. This is a read-only snapshot and
never installs, upgrades, or repairs components. Run nur ecosystem ensure
explicitly when you want those changes.
nur browser¶
Set up the real-browser browser tool for your default Chromium browser
(Arc, Chrome, Edge, Brave, …). Stages the tmwd_cdp_bridge extension and
walks you through the one-time Load unpacked click.
nur browser setup¶
Stage the extension (no download), detect the default browser, copy the staged
path to the clipboard, and open chrome://extensions.
nur browser status¶
Show detected default browser + extension staging state.
Also runs automatically from the installer after ecosystem ensure.
nur install-hook¶
Install the Orca agent hook for usage/status reporting.
nur gateway¶
Run headless as a Telegram bot — each inbound message is an agent turn in the current project, with the answer sent back (one session for continuity, tools auto-approved). Get a token from @BotFather.
nur gateway [--token <TOKEN>] [--chat <CHAT_ID>]
# token also from $TELEGRAM_BOT_TOKEN · chat from $TELEGRAM_CHAT_ID
| Flag | Description |
|---|---|
--token |
Bot token (else $TELEGRAM_BOT_TOKEN) |
--chat |
The one chat the bot answers (else $TELEGRAM_CHAT_ID). Required to run anything: without it the bot only pairs, replying to each sender with their chat id and running nothing, because every turn auto-approves tools, bash included |
nur local¶
Managed local models — bundles llama.cpp (fetches a prebuilt llama-server
for your platform on demand), downloads a GGUF sized to your RAM, and runs it on
127.0.0.1:8080 (the llama.cpp (local) catalog provider). No API key.
nur local up [<tier|url>] # size to RAM (or a tier: small|medium|large, or a direct .gguf URL)
nur local status # server · downloaded models · running state
nur local down # stop the managed server
nur local models # list the built-in tiers
Also available in the TUI as /local.
nur bench¶
Benchmark models on your own tasks: record a task once, replay it across models in isolated git worktrees, and score them (pass/fail via a check command, wall time, tokens).
nur bench add <name> "<prompt>" [--check "<shell cmd>"] # exit 0 of the check = pass
nur bench list
nur bench remove <name>
nur bench run <name|all> [--models <m1,m2>] # default: the active model
Also available in the TUI as /bench.
TUI slash commands¶
Type these inside the nur TUI. Aliases are shown in the same row.
| Command | Purpose |
|---|---|
/help · /commands |
Keys + command list |
/exit · /quit |
Quit |
/clear |
Clear the transcript display only — context and saved session history are untouched |
/new |
Start a fresh session |
/compact |
Honor configured Jev pruning without a summary; otherwise summarize (details) |
/sessions · /resume |
Browse & open past nur sessions (/resume <id> also works). Press c to switch to the takeover window |
/takeover · /hijack |
Cross-agent session migration. Opens the takeover window (same chrome as /sessions) listing migratable Claude Code · Codex · Cursor · Grok Build sessions from all workspaces (Tab narrows to here); ↵ imports one and resumes it natively. Press c to switch back to sessions. /takeover ls [agent] lists them; /takeover <agent> [id\|latest] imports directly |
/login |
Provider + API key or browser sign-in |
/logout |
Sign out of the active provider — clears its credential and its saved per-provider copies. /login never clears anything. |
/model · /models |
Show and switch models for the active provider. OpenCode rows show a friendly alias where the wire id is cryptic (e.g. x-preview-f-free · Ox Alpha Free), and the filter matches aliases too — typing ox finds it. |
/plugins · /plugin |
Browse / install / enable marketplace plugins |
/akarso |
Akarso social posting: /akarso (auth), accounts, posts; publishing/scheduling runs through the akarso tool with approval |
/openseo |
Open OpenSEO (open-source Semrush/Ahrefs alt) dashboard + MCP setup; SEO via MCP |
/dialkit |
Activate the dialkit skill — live-tune interface parameters (React/Svelte/Vue/Solid) |
/effort |
Reasoning effort: low, medium, high, xhigh, max, ultracode. Saved to config; shows what the active route receives |
/mode |
Permission mode: manual | plan | auto (or Shift+Tab) |
/manual |
Switch to manual mode (approve writes/shell) |
/plan |
Switch to plan mode (read-only explore) |
/auto |
Switch to auto-approve mode |
/cd |
Change working directory (tool sandbox root) |
/pwd |
Print the working directory |
/budget |
Session spend ceiling |
/turns |
Per-session agent-turn ceiling (0 = unlimited) |
/poor |
Cost-saver lean prompt |
/usage · /cost |
Token usage + estimated cost this session |
/ledger [today\|7\|month\|all] |
Local usage across seven agents; ledger reference |
/context |
Context-window utilization |
/status |
Session snapshot: model · mode · cwd · tokens |
/doctor |
Health check: version · auth · ecosystem · shell · TypeSafe/Jev (ready on a local engine with no key) |
/theme |
Live theme picker (41 themes) · /theme <name> sets one · /theme transparent toggles see-through · /theme motion toggles reduced motion for web/SSH terminals |
/fusion |
Multi-model debate → one synthesized answer |
/local |
Run a model locally via bundled llama.cpp |
/bench |
Benchmark models on your tasks; /bench optimize <name\|all> [gens] [pop] evolves the standing instruction against them (GEPA — costs tokens) |
/failover |
Cross-provider failover + privacy tiers |
/undo |
Revert the last file edit this session |
/receipt |
Session receipt — hash-chained verification |
/cua |
Computer-use desktop driver: on | off | status |
/graph |
Inline live execution-graph card for the current turn |
/sidegraph |
Right-sidebar live node-graph of the current query: root prompt, thinking, tools, subagent fan-out, steers, interrupts — as boxed flow nodes. Bare /sidegraph toggles the panel, off freezes refresh, on resumes, hide closes. Mouse wheel over the panel scrolls it; it follows the bottom otherwise. Hidden automatically when the window is too narrow. |
/swarm |
Inline subagent activity grid — a live tiled pane per subagent (aliases /subagents, /agents). Auto-surfaces the moment a subagent spawns, so you no longer have to run it first to watch a fan-out. detail adds the status row, off freezes, clear drops finished runs, hide removes the card and suppresses auto-surfacing for the rest of the turn (it re-arms on the next turn). |
/subagents · /agents |
Alias of /swarm — inline subagent grid, live panes per subagent |
/fractal |
Recursive agent tree — hierarchical loops in git worktrees: init · node list · node status <name> · node start <name> · attach <name> · open. open launches fractal's own full-screen dashboard: nur hands the terminal over and restores it when you quit. ⚠️ Unix only — see below. |
/optmem · /memo |
OptMem permanent memory (~/.optmem): status · wake · note · nap · recall · zoom · forget · config · doctor |
/typesafe · /jev |
Jev (TypeSafe System One) boost layer: status · on/off · ask <state> (docs/typesafe.md) |
/typesafe-ai |
Loads the TypeSafe skill (how to design and use judgments) - distinct from /typesafe, which is the layer's status/controls |
/enclave |
Enclave security agents over native MCP: status · tools [name] · login (docs/enclave.md) |
/headroom |
Context compression doctor (inline tool-result compress on by default) |
/prewalk |
OMP-style: strong model plans, then cheap/smol at first edit after todos (on | off | status | into <model> | reset). Off by default. |
/egaki |
Image/video gen via egaki (login --provider chatgpt supported) |
/image <path> |
Stage an image in the composer for vision; F4 previews it (generation is /egaki) |
/tb · /terminal-browser |
terminal-browser: open | ls | action | setup (Windows host fallback via agent-browser-cli) |
/factory-overnight |
Fractal-first overnight factory from HANDOFF.md (Unix preferred) |
/pen · /drawings · /penecho |
Penecho canvas — ink, MathJax, plots, animations; /drawings lists saved canvases |
/draw |
Open / build tldraw offline boards (/draw <file.tldraw>, /draw install, /draw <idea>). New static boards save to the Desktop. Opening a board auto-enables document scripts (canvas API script-workspace → applied) for interactive agent-shape files. |
/steer |
Inject a message into the running turn without cancelling it |
/scan |
Map the codebase → shareable foglamp scan |
/goal |
Set a standing session goal (starts a goal-driven turn; stalls auto-continue while the goal is active) |
/btw |
One-off note attached to the next message |
/bro |
Chill mode: plain words, straight answers (toggle) |
/adhd |
Sticky ADHD-friendly output for this session (toggle) |
/site-cli |
Skill: HAR → derived site API client/CLI |
/fable-method |
Skill: Fable think-act-prove loop |
/fable-loop |
Skill: orchestrated Fable multi-step loop |
/fable-judge |
Skill: adversarial verification of finished work |
/tech-spec |
Skill: typed call-stack architecture handoff |
/design-eng |
Skill: Emil design-eng UI/motion craft |
/skeuo |
Skill: skeuomorphic UI (/skeuomorphic-ui) - depth, texture, physical affordances |
/test-driven-development |
Skill: TDD red-green-refactor |
/systematic-debugging |
Skill: root-cause-first debugging |
/<skill> |
Any installed skill — sticky toggle, or /<skill> <prompt> one-shot |
/codesearch · /cs |
Fast ripgrep over the workspace |
/mc · /mcp |
Manage MCP servers via Executor |
/skills |
List installed skills. /skills trust approves this project's local skills (.nur/skills, .claude/skills, .agents/skills) - held inert until trusted, re-held on edit |
/memory |
Show the ~/.nur memory excerpt |
/graphify |
Knowledge graph: status / query / extract |
/graphjin |
Live data (/gj): catalog | schema | help | explain | query | security | ask. Writes go through the model so they hit the approval gate. |
/plur |
Shared engram memory |
/ruflo |
Vector memory / swarm |
/ecosystem |
Check / provision the ecosystem |
/todos |
Show the session task list |
/init |
Generate a NUR.md project guide |
/config |
Show config + data paths |
/permissions |
Show or reload allow/deny/ask rules; trust / untrust this project's allow rules |
/hooks |
Show local tool hook status |
/feedback |
File a GitHub issue from here |
/bug |
Report an issue (GitHub link) |
/tips |
Mouse + keyboard interaction tips |
Project instruction files¶
NurCLI loads project-level instructions from your working directory at session start:
| File | Purpose |
|---|---|
NUR.md |
Primary project instructions |
AGENTS.md |
Agent conventions |
CLAUDE.md |
Also loaded |
Safe workspace¶
When launched from a drive root (C:\ or /), NurCLI auto-selects a safe workspace by checking (in order):
- Git repository root
- Last session's working directory
~/Laboratory(or fallback)