CLI reference

Every command, flag and exit code of nex — the terminal surface of the Nexrall coding agent. For the guided tour, start with Nexrall CLI; this page is the lookup table.

nex --help prints the command list, nex <command> --help the details of one command, and --version the installed version.

Invocation

Form	What it does
nex	Interactive session in the current directory.
nex "fix the failing test"	Interactive session, first message already sent.
nex --print "summarise src/"	One-shot: print the answer and exit.
echo "..." | nex "what broke?"	Piped stdin becomes part of the turn.
nex --bg "run the release checks"	Background job; prints a job id — follow it with nex logs / nex attach.
nex --bg --exec 'npm run build'	Run a raw shell command as a background job (no agent, no model) — same registry: nex logs / nex attach / nex kill.

Two traps worth internalising:

• -p, -t and -u no longer exist: they used to select a model by tier word, and model selection is by name now (nex -m claude-opus-5-5). Using one is refused with the replacement named. Headless one-shot printing is nex --print.
• With flags that take list values (--allowedTools, --mcp-config, --add-dir…), put the prompt before the flag or it is swallowed as a value.

Global flags

Model

Flag	What it does
-m, --model <name>	Explicit model — claude-opus-5-5, gpt-6-sol, deepseek-flash, …
-e, --effort <level>	Thinking effort; the real levels depend on the model (DeepSeek low|high|max, Qwen low|high). Load a model and run /effort with no argument to see its scale.
--fallback-model <name>	Retry the turn once on this model if the main one is overloaded or unreachable (needs --output-format).

Permissions & safety

Flag	What it does
-y, --yolo	Auto-approve all tool calls, no permission prompts.
--mode <mode>	Starting permission mode: ask | edit | auto | plan.
--permission-mode <mode>	Same, also accepting the Claude Code names (default | acceptEdits | dontAsk | bypassPermissions). With --output-format, anything that would prompt is denied instead of auto-approved.
--plan / --readonly / --auto	Start in plan mode (switchable) / plan mode that cannot be switched off / auto mode (the default; irreversible actions are still confirmed).
--allowedTools, --allowed-tools <rules…>	Tools or rules to allow without asking — "Bash(git *)" Edit (comma or space separated).
--disallowedTools, --disallowed-tools <rules…>	Deny rules ("Bash(rm *)"); deny always wins.
--tools <list>	Exactly these built-in tools ("Bash,Read,Edit", "default", "" for none) — the rest are removed, not just unapproved.
--permission-prompt-tool <tool>	An MCP tool (mcp__server__tool) that answers permission prompts in non-interactive runs, instead of nex denying them.
--audit [path]	Log every tool call and refusal to a JSONL trail (default .nexrall/audit/<session>.jsonl).

Session & directories

Flag	What it does
-d, --dir <path>	Working directory (default: the current one).
-r, --resume [id]	Resume the last session, or a specific one.
-c, --continue	Continue the latest conversation in this folder.
--session-id <id>	Use this id for a new conversation (letters, digits, -, _), so a script can find it again.
-n, --name <name>	Name the conversation; nex -r <name> resumes it by that name.
--fork-session	With --resume/--continue: branch into a new session instead of continuing the original.
--no-session-persistence	Do not save this run to disk (needs --output-format; it cannot be resumed).
-w, --worktree [name|PR/MR URL]	Isolate the session in its own worktree — a separate directory (and, in a git repo, its own branch) so it cannot overwrite files another session is touching. Omit the name for an auto-generated one; pass an existing name to reattach to it. New worktrees start from the remote default branch by default so unpushed commits stay out of them; set worktree.baseRef to "head" to branch from local HEAD instead. Passing a GitHub pull-request or GitLab merge-request URL branches the worktree from that PR/MR head instead (fetched from origin; the tree is named pr-N/mr-N, so the same URL reattaches).
--add-dir <dirs…>	Extra directories the agent may read and edit.
--plugin-dir <paths…>	Load a plugin from a directory, a .zip or a .tar.gz archive for this session only (repeatable). The path may be a plugin directory, an archive of one, or a directory of several. A requested plugin that cannot be loaded fails the run — no silent partial loads. Session plugins
--plugin-url <urls…>	Download and load a plugin .zip/.tar.gz for this session only (repeatable; the archive type is sniffed from the content, so a URL without an extension works).

One-shot & scripting

Flag	What it does
--print	One-shot, non-interactive run that prints the answer and exits (same as --output-format text).
--output-format <fmt>	text | json | stream-json — implies auto-approve.
--input-format <format>	text (default) or stream-json: read the prompt as Claude-Code-style NDJSON user messages on stdin.
--json-schema <schema>	JSON Schema the final answer must satisfy; the result gains structured_output. Exit 3 if it does not validate.
--max-budget-usd <amount>	Stop the run once it has spent this many dollars. Exit 2.
--max-turns <n>	Stop after N agent rounds. Exit 4.
--bg	Run the prompt in the background (headless); returns a job id.
--exec <command>	With --bg: run this raw shell command instead of an agent prompt (nex --bg --exec 'npm run build').
--verbose	Progress detail (tool calls, timings, usage) to stderr; stdout stays machine-readable.
--include-partial-messages	Stream model deltas as they arrive (needs stream-json).
--include-hook-events	Hook lifecycle events in the stream (hook_started / hook_progress / hook_response).
--replay-user-messages	Echo each stdin message back on stdout as it is consumed.
--share <id>	Publish this headless run to the live web viewer under <id> (app.nexrall.com/live/<id>) — needs --output-format. The id takes letters, digits, - and _ (max 64), e.g. cloud-123. The interactive equivalent is /share; cloud sessions publish their pod run with it.
--mcp-config <configs…>	Load MCP servers for this run from JSON files or inline JSON.
--strict-mcp-config	Use only those servers, ignoring the user and project mcp.json files.

Prompts, agents & settings

Flag	What it does
--append-system-prompt <text> / --append-system-prompt-file <path>	Extra instructions appended to the project brief for this run.
--system-prompt <text> / --system-prompt-file <path>	Replace the project brief (nexrall.md + memory + global instructions) for this run.
--agents <json-or-file>	Define extra sub-agents for this run — a JSON object { "name": { "description", "prompt", "tools", "model" } } or @file.json.
--agent <name>	Run this session as that agent (its prompt, tools and model) — from .nexrall/agents, a plugin, --agents or a builtin.
--settings <file|json>	Settings (permissions, hooks…) for this run only; merged over the user and project settings.
--bare / --safe-mode	Start without discovery: no nexrall.md/memory, skills, plugins, hooks or MCP config files.

Terminal & UI

Flag	What it does
--fullscreen	Draw the session on the alternate screen: re-wraps on resize, PgUp/PgDn page through it (/fullscreen toggles it later).
--ax-screen-reader	Screen-reader mode: flat labelled lines, no spinner repaints, numbered menus, bell when the session needs you. Also NEXRALL_AX_SCREEN_READER=1 or the axScreenReader setting.
--no-banner	Skip the ASCII banner (useful in scripts and pipes).
--no-color	Disable colored output (also honours NO_COLOR).
--debug / --debug-file <path>	Write request timing, retries and errors to a debug log file; --debug-file implies --debug.

Commands

nex auth, nex login, nex logout

Command	What it does
nex auth	Sign in. In a terminal it asks how: browser (Google, Apple, company SSO, or email + password — the only method that works for an account with no password), email + password typed here, or a token. nex login is an alias.
nex auth --browser	Sign in through the browser. Opens app.nexrall.com/auth/vscode?cli=1, shows a 5-minute code, and finishes the sign-in when you paste it.
nex auth --code <code>	Finish a browser sign-in with a code you already copied (opens no browser — use it on a headless box).
nex auth --token <token>	Save a token directly, for CI or headless setup. Prefer NEXRALL_TOKEN where you can. The token is checked against the API before it is saved; a network failure saves it with a warning, a rejected token saves nothing.
nex auth --password	Skip the method menu and ask for email + password.
nex auth status [--json]	Show who is signed in; --json for machine-readable output.
nex logout	Sign out on this machine: revokes the saved refresh token server-side, then deletes the local config. A token supplied through NEXRALL_TOKEN is not touched — unset it too, or the CLI stays signed in.

Inside a session, /logout does the same thing without leaving the chat.

nex doctor

Command	What it does
nex doctor [-d, --dir <path>] [--fix]	Check everything a session depends on — Node, sign-in, network, terminal capabilities, MCP servers, storage — and print a fix beside each problem. Exits non-zero when something is wrong, so it doubles as a CI preflight. --fix applies the repairs doctor can do itself (abandoned lock files, orphaned lock staging files, old temp workspaces) before printing, so fixed rows show the post-fix state.

nex billing

Command	What it does
nex billing	Show which budget pays (wallet or team) and what is left.
nex billing use <team|personal>	Switch what usage is billed to.

nex schedule (alias nex routines)

Command	What it does
nex schedule / nex schedule list [--json]	List cloud schedules.
nex schedule add -e, --every <interval> <task…>	New recurring task. Interval units s, m, h, d, from 15m to 7d (90m, 2h, 1d); --start-url <url> where the cloud agent starts, --domains <list> comma-separated hosts it may visit, --disabled creates it paused.
nex schedule pause <id> / resume <id> / run <id>	Pause, resume, or run now (the cloud runner picks it up within ~60s).
nex schedule rm <id> [-y]	Delete — no further runs fire; history stays on the server.
nex schedule runs <id> [--json]	Recent runs of one schedule, newest first.

nex cloud

Cloud coding sessions — a one-task run of the coding agent on Nexrall's infrastructure: the repo is cloned into an isolated Pod, the agent works headless, and a branch + pull request come back. Distinct from nex schedule, which runs recurring browser tasks. Early access — the server refuses with a sentence when the account is not enabled.

Command	What it does
nex cloud / nex cloud list [--json]	Your sessions, newest first — id, status, repo, and the result once there is one (the PR, the branch, or the error).
nex cloud run "<task>" --repo <owner/name> [--base <branch>] [--pat <token>] [--open]	Start one. Base defaults to main. The GitHub token covers cloning a private repo and the push + PR: prefer NEXRALL_CLOUD_PAT over --pat (argv is visible in ps); a public repo clones without one. --open opens the live viewer.
nex cloud logs <id> [-f, --follow] [--tail <n>] [--json]	The pod's log — --tail default 300, max 2000; -f follows until the run ends (exits non-zero when it failed). A finished session's log is the tail captured when its pod was deleted.
nex cloud stop <id>	Request a stop — the runner deletes the pod within ~10s.
nex cloud watch <id> [--print]	Open the live viewer (or with --print, just print the URL) — the same app.nexrall.com/live/… viewer a shared local session uses.

The delivered branch is nexrall/cloud-<id>, and the PR opens against the base branch when the run ends. Server-enforced caps: 1 running session at a time, 3 queued, 10 sessions per rolling 24h, and a 90-minute wall clock per session. Model spend bills to the same wallet or team as any other run.

nex mcp

Command	What it does
nex mcp list [--json]	Servers and their state.
nex mcp add <name> [target…]	Register a server — stdio by default (nex mcp add fs -- npx -y @modelcontextprotocol/server-filesystem .), or remote with -t, --transport http|sse <url>. Flags: -e, --env KEY=value (stdio, repeatable), -H, --header "Name: value" (remote, repeatable), --client-id / --client-secret for servers without dynamic registration, -s, --scope project|user (default project).
nex mcp add-json <name> <json> [-s <scope>]	Register from raw JSON.
nex mcp get <name>	Print one server's entry.
nex mcp remove <name> (alias rm)	Unregister a server.
nex mcp login <name> [--client-id <id>] [--client-secret <secret>]	OAuth sign-in; the flags override credentials stored in mcp.json. Details
nex mcp logout <name>	Forget the stored tokens.
nex mcp serve [--cwd <dir>]	Run nex as an MCP server on stdio; --cwd is the workspace root relative paths resolve against.

nex channel push

The source side of channels: push a message into a live session and, with --wait, print the turn's answer back.

Command	What it does
nex channel push <text…> --url <push URL> [--token <token>] [--source <slug>]	POST the message with x-channel-token; a rejected token/id/text is one readable line.
nex channel push … --wait [--timeout <seconds>]	Poll the result endpoint until the session answers, then print the reply. Exit codes: 0 answered · 1 failed · 3 discarded · 4 timed out.
nex channel push … --json	Machine-readable outcome (status, reply/noText, truncation).

--token can instead come from NEXRALL_CHANNEL_TOKEN (argv is visible in ps). The push URL and token are printed once by /channel open inside the session.

nex usage export

Machine-readable usage from the local event stream (see Usage export & telemetry).

Command	What it does
nex usage export	JSON report, all sessions (default).
nex usage export --format jsonl|csv	JSONL (meta row + session rows) or CSV (one row per session).
nex usage export --since 7d --until 2026-10-01 [--session <id>]	Window (7d, 48h, 90m, 2w or a date) and/or one session.
nex usage export --limit <n> / --all	Log files to read, newest first — default 500; the report flags truncated when the cap bites.
nex usage export --out <file>	Write to a file instead of stdout.

Exit codes: 0 success · 1 session not found · 2 usage error. Cost honesty: an unreported cost is costMissing, not $0.

Background jobs

nex --bg "<prompt>" runs a headless agent; nex --bg --exec "<command>" runs a raw shell command instead. Both land in the same registry (nex jobs / logs / attach / kill / rm / respawn); a shell job is marked ! in the listings.

Command	What it does
nex jobs	List background jobs started with --bg.
nex logs <id> [-f, --follow]	Print a job's output; -f keeps following until it ends.
nex attach <id>	Watch a job live (tool calls, text, result). Ctrl+C detaches; the job keeps running.
nex stop <id> / nex kill <id>	Stop a running job (same thing; stop matches Claude Code's name).
nex rm <id>	Delete a finished job's records, log included.
nex respawn [id] [--all]	Restart job(s) onto this nex build, replaying the original command; --all restarts every running job.

nex agents [--json] [--all] [--cwd <path>]

Everything in the background in one table: --bg jobs, live sessions, background sub-agents, and this project's shared tasks — including work from other sessions on this machine. --json prints a stable schema; --all also includes finished work; --cwd limits it to a directory.

nex tasks

This project's shared task board from the shell — the same board sessions use through their tools (create_shared_task, claim_task), and the same ids nex agents shows. A shell claim races a session's claim exactly as two sessions would race each other. Exit codes: 0 done · 1 refused (not found, held by someone else, blocked, bad usage).

Command	What it does
nex tasks [--all] [--json] [--cwd <path>]	The board; --all includes completed tasks, --json marks stale claims per task.
nex tasks add <content…> [--blocked-by <ids>] [--id <id>]	Create a pending task sessions can see and claim; --blocked-by takes comma-separated ids this one waits on.
nex tasks claim <id> [--as <name>]	Take a task (default holder shell:<user>).
nex tasks done <id> [--as <name>] (alias complete)	Mark it completed; --as must match the holder's name when it is held.
nex tasks release <id> [--as <name>] (alias unclaim)	Give a claimed task back to the board (in progress → pending).
nex tasks rm <id> [-y, --yes]	Remove the record entirely (asks first unless -y).

An id may be any unique prefix, and every verb takes --cwd <path> to act on another directory's board (and --json for scripts).

nex plugin

Command	What it does
nex plugin install <source> [--project] [--name <name>] [-f, --force] [-y, --yes] [--config <key=value>]	Install from a short name, owner/repo#ref/subdir, a git URL or a local path. --project installs into ./.nexrall/plugins (default: ~/.nexrall/plugins). Missing dependencies install too. --config (repeatable) sets the plugin's userConfig values at install time. Plugin configuration
nex plugin remove <name> [--project] [--keep-data] (alias uninstall)	Remove; --keep-data keeps ~/.nexrall/plugin-data/<name>.
nex plugin prune [--project] [--dry-run] [-y] [--keep-data] (alias autoremove)	Remove auto-installed dependencies nothing needs any more.
nex plugin update [name] [-y]	Update one plugin, or all.
nex plugin list [--enabled] [--disabled] (alias ls)	What is installed; the flags filter by state, and a disabled row carries a ⏸ disabled marker.
nex plugin disable <name> / nex plugin enable <name>	Toggle a plugin without removing it — a disabled plugin's commands, skills, agents, hooks, MCP servers and bin/ PATH entries stop loading. Nothing is deleted (the data directory stays).
nex plugin search [query] / info <name>	Search the registry, show one entry.
nex plugin source list / add <name> <spec> [--project] / remove <name> [--project]	Team plugin sources: bind a short alias to a plugin repo. --project writes ./.nexrall/settings.json so the team shares it. Official plugins
nex plugin configure <name> [--project] [--values-stdin] [--json]	Show a plugin's userConfig options and which are set (values masked for sensitive); --values-stdin saves one JSON object {key: value} read from stdin. Default save scope: the plugin's install scope. Plugin configuration
nex plugin validate [dir] [--json]	Check a plugin directory before installing: manifest + userConfig schema (strict), hooks.json/mcp.json (a shell-form hook command that uses ${user_config.*} is an error), undeclared ${user_config.KEY} references, unreachable MCP entries, insecure URLs. Exit 1 on errors.
nex plugin eval [dir] [--case <name>] [--runs <n>] [--threshold <n>] [--judge-model <m>] [--max-cost-usd <n>] [--no-without] [--json]	Run a plugin's eval suite (evals/<case>/prompt.md + graders/*.md): each case runs N times with and without the plugin, graders score each run, the report lands in evals/results/<ts>/aggregate-result.json. Exit 0 all cases passed, 1 otherwise, 2 usage error. Plugin evals
nex plugin eval init [dir]	Scaffold one working eval case (evals/example/prompt.md + a regex grader) in a plugin directory; refuses to overwrite an existing evals/example.

nex auto-mode

Command	What it does
nex auto-mode defaults [--label <name>]	The built-in hard/soft limits (labels + prose). $defaults in your lists expands to these.
nex auto-mode config	The effective config: which file set each key, the limits, classifier state, and ignored project files.
nex auto-mode critique [--model <name>]	One model call reviewing your config for gaps, with concrete fixes.
nex auto-mode reset [-y]	Remove the autoMode block from ~/.nexrall/settings.json (managed policy untouched; non-TTY needs -y).

Commands inside a plugin (and its agents) load at session start — see Plugins.

nex sessions

Command	What it does
nex sessions	List saved sessions.
nex sessions -d, --delete <id>	Delete one.
nex sessions --clear-all	Delete all saved sessions.
nex sessions --export <id> [--out <file>]	Export a session (conversation + event log) as a portable JSON bundle.
nex sessions --import <file>	Import a bundle from another machine or client.
nex sessions --events <id> [--last <n>] [--json]	Show the session's event stream — what other clients read (default 20 events).
nex sessions --pr <url>	Sessions whose transcript mentions this pull/merge request URL — the creator, then anyone who revisited it; nex --resume <url> continues the newest directly.

nex project purge [dir]

Delete this project's local state: saved sessions, their event logs, the shared task board, rewind checkpoints, and the prompt-history rows for that directory. The project's own .nexrall/ (committed configuration) is never touched, and neither is anything belonging to another project.

nex project purge             # this directory, after a confirmation
nex project purge --dry-run   # list what would go, remove nothing
nex project purge -y          # non-interactive (required when stdin is not a TTY)

nex update

Command	What it does
nex update [-c, --check] [-y, --yes]	Update nex to the latest version, or just check. Also /update in a session.

Exit codes

Code	Meaning
0	Success.
1	An error: bad usage, a failed run, nex doctor findings.
2	--max-budget-usd was reached.
3	--json-schema validation failed.
4	--max-turns was reached.

In a headless run, anything that would normally prompt for permission is denied instead of approved (--permission-mode), and irreversible commands keep their own guard — see Safety in headless mode.

Files & state

Path	Holds
~/.nexrall/cli-sessions/	Saved conversations and their event streams (NEXRALL_CLI_SESSIONS_DIR moves it).
~/.nexrall/cli-bg/	Background job output.
~/.nexrall/mcp-auth.json	MCP OAuth tokens (0600; NEXRALL_MCP_AUTH_FILE moves it).
~/.nexrall/mcp.json, .nexrall/mcp.json	MCP servers, user- and project-scope.
~/.nexrall/plugins/, .nexrall/plugins/	Installed plugins.
~/.nexrall/plugin-data/<name>/	Per-plugin data, kept by --keep-data.
~/.nexrall/settings.json, .nexrall/settings.json	Settings (see Configuration); a project .nexrall/ also holds agents/, skills/, rules/ and commands/.
.nexrall/audit/<session>.jsonl	The --audit trail.

See also

• Nexrall CLI — the guide, from install to channels.
• Slash commands · Interactive mode.
• Environment variables · Permission modes & rules · MCP.