Skip to content

Commands

Full CLI reference for NurCLI.

Usage

nur [OPTIONS] [PROMPT]
nur <COMMAND> [ARGS]

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.

nur run <PROMPT...> [OPTIONS]
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 -v in text mode; in the JSON formats they go to stderr or become status events.
  • Exit codes tell failures apart without scraping text: 0 ok · 1 unexpected error · 2 configuration · 3 authentication (no key, or the provider rejected it with 401/403) · 4 provider (other HTTP errors, network) · 5 budget or turn limit · 6 the model declared BLOCKED: <what it needs> (the answer is still printed) · 130 cancelled. nur "<goal>" --continuous uses the same codes (5 for --max-iters, 6 for a declared blocker). Also in nur --help.
  • The result object (json, and the last line of stream-json): ok, exit_code, result (the answer, or null on error), error, blocked (the text after BLOCKED:), session_id, model, provider, tool_calls, duration_ms, usage (input_tokens, output_tokens, total_tokens, estimated_cost_usd) and layers.
  • 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, a layers event in stream-json, the layers field of the json result. 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.jsonl carries purpose: chat for the turn itself, compaction / compaction-remote for summaries, fusion for panel members, subagent for 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 <SUBCOMMAND>

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).

nur auth login [--provider <ID>] [--browser] [--import] [--key <KEY>] [--model <MODEL>] [--yes]
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 status

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.

nur sessions [--limit <N>]
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 usage

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).

nur install
# alias:
nur self-install

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.

nur doctor

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 <SUBCOMMAND>

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).

nur ecosystem ensure [--force]
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 refresh-skills

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 ecosystem status

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 <SUBCOMMAND>

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 setup

nur browser status

Show detected default browser + extension staging state.

nur browser status

Also runs automatically from the installer after ecosystem ensure.


nur install-hook

Install the Orca agent hook for usage/status reporting.

nur install-hook

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):

  1. Git repository root
  2. Last session's working directory
  3. ~/Laboratory (or fallback)