Documentation menu
CLI reference
Run nid help for the grouped overview, nid help <command> for one command,
or nid help <topic> for a short guide (getting-started, billing, approvals,
groups, config).
<value> is required, [value] optional, and ... accepts multiple words/items.
Session IDs use group/name; when only one group has a session with that name, the
name alone works (nid send lead "..."), and a tie goes to the current repository's
group. Task numbers are scoped to a group. Where a group is optional, nid chooses the
single group associated with the current repository, then the only group overall;
ambiguity asks you to pass a name. Misspelled commands, agents, sessions and groups get
a "Did you mean ...?" suggestion.
Output conventions: data goes to stdout unchanged; on a terminal, state-changing commands
add a Next: hint and slow steps a spinner on stderr. NO_COLOR turns colors off,
FORCE_COLOR=1 forces them, NID_HINTS=0|1 turns hints off or on everywhere, and
NID_ASCII=1 uses ASCII symbols (automatic on legacy Windows consoles).
Shell completion#
nid completion <bash|zsh|fish|powershell> prints a script completing commands,
subcommands, options, agent names and (with the daemon running) group and session names.
| Shell | Install |
|---|---|
| bash | nid completion bash >> ~/ |
| zsh | nid completion zsh > "${fpath[1]}/ |
| fish | nid completion fish > ~/ |
| PowerShell | nid completion powershell >> $PROFILE |
The terminal app#
| Command | Behavior |
|---|---|
nid | In a repository: open the terminal app (first run sets up nid.yaml). Not on a terminal: print the grouped help. |
nid "<goal>" | Open the app with this goal sent to the team (starting it if needed). Without a terminal it exits with code 2; use -p. |
nid -p "<goal>" | --yes (allow permission requests), -g, --group <group>, --timeout <seconds>; run without the app, progress on stderr, summary on stdout; exit 0 when the lead reports DONE, 1 when the team stopped, hit its budget or timed out. |
Inside the app: Enter sends, Tab completes commands and @names, ↑/↓ recall history, Esc
interrupts the working agent, Ctrl-O expands tool calls, Ctrl-C twice leaves (the team keeps running), @name
addresses one agent and /help lists the slash commands. See
keys and slash commands.
Install, initialize and launch#
| Command | Flags / behavior |
|---|---|
nid --version | Print the installed version. |
doctor | Diagnose CLI versions, install/update state, agents, daemon and sandbox. |
agents | -C, --dir <dir>, --json; installed built-ins and resolved custom agents. |
models [agent] | -C, --dir <dir>, --role <role>, --refresh, --json; the models each agent can use, default marked with *, and how a running session switches. Never spends tokens; Codex's list is cached 10 minutes. See agents. |
init [dir] | -y, --yes, --force, --preset lead|review|solo, --group <name>, --goal <text>, --budget <usd>, --yolo, --model <session=model> (repeatable; a bare model goes to every member whose agent takes it); write project configuration. |
spawn <agents...> | Start agents specified as agent[:name][@model]; flags below. |
up [group] | -f, --file <file>, -C, --dir <dir>, repeatable --copy <path> / --link <path>; start a declared team. |
migrate | --dry-run, --force; finish the move from terminid or pawmux: migrate ~/.terminid (or ~/.pawmux) if not done yet and rename this project's terminid.yaml or pawmux.yaml to nid.yaml. See upgrading from terminid. |
update | --check, --version <version>, --channel stable|beta|alpha (saved for later updates); update a compiled installation and restart its daemon. No token needed. A daemon that has not answered for 20 seconds is only stopped by force after a yes at the prompt or with --force-restart. |
auth [status] | --json; per managed agent (claude, codex, gemini): the billing a new session gets, the subscription login and where an API key would come from. See billing. |
auth set <agent> | --api-key [key] (omit the value to type it hidden or pipe it on stdin); store an API key for billing: api in the OS keychain where available. |
auth rm <agent> | Remove a stored API key. |
uninstall | --yes (no questions, keeps data), --purge (with --yes: also delete NID_HOME); stop the daemon, turn autostart off, remove the binary and installer PATH entry. See uninstall. |
The table omits the nid prefix on subcommands. For example, doctor means
nid doctor. Init defaults and setup detection are explained in
getting started.
spawn accepts -g, --group <group>, --goal <text>, --budget <usd>,
--policy lead|peers, --role <role>, -p, --prompt <text>, --yolo, --shared,
--billing subscription|api|auto (billing), --compression on|off (compression settings),
--no-auto-restart, --setup <cmd>, repeatable --copy <path> and --link <path>,
and -C, --dir <dir>. Worktrees and permission choices are described in
concepts and security.
Observe and communicate#
| Command | Flags / behavior |
|---|---|
ls [group] | Sessions, their model (MODEL: what the agent reports, else the configured one marked (configured), else default), states, cost (billed, or est. for subscription estimates), tokens, context-window use (CONTEXT) and requests. |
groups | Teams with session/task counts and spending (billed + est.). |
status | --json; cross-group summary, with each group's models (MODELS). |
dashboard | --port <n>, --no-open; create a fresh one-time sign-in link. |
logs [target] | -f, --follow, -n, --lines <n> (40), -v, --verbose; session/group events. |
watch [group] | -v, --verbose; stream group activity and attention alerts. |
top [group] | Terminal overview; q or Ctrl-C quits, piped output is one frame. |
send <target> <text...> | Message a session or broadcast to a group. |
attach <session> | -v, --verbose; follow and chat. --native opens the vendor TUI, --force allows cutting off a turn for native takeover, --tty controls a PTY session. |
inbox [group] | Human-addressed messages and pending questions; marks retrieved messages read. |
questions [group] | -a, --all includes answered/timed-out questions. |
answer <id> <text...> | Answer a pending question. |
approvals | -a, --all includes resolved requests. |
approve <id|session> | Allow selected request(s); --deny rejects. An unknown or already answered id exits 1. |
stop [target] | Stop a session/group (default: this repo's team) without removing its work. |
resume [target] | Restart stopped sessions on their conversations where supported. Sessions that are already running are left alone (nothing to do, no error). A group resume also skips sessions that another resume is starting at the same moment, such as the daemon resuming them after a crash. |
interrupt [target] | Interrupt current work in one session or a group. |
model <target> [model] | --role <role> (groups), --json. Switch a session's model, or every session of a group (or of one role), keeping the conversation. Never mid-turn: an idle session switches now, a busy one when its turn ends, a stopped one on its next resume. Codex and ACP agents switch in place; Claude Code restarts on the same conversation with the new --model; PTY agents only after a restart (stop, then resume). Billing never changes (a subscription session stays on the subscription). An unknown model fails with a did-you-mean from nid models; a model the vendor marks unavailable on your plan warns, and if the agent refuses it, the session goes back to its previous model and reruns that input. Without a model: an arrow-key picker in a terminal (current and default marked; Enter switches, Esc cancels), otherwise the current models and the list. |
rotate <session> | --mode auto|compact|handoff; free context now (idle) or after the current turn. See long-running sessions. |
target means group/name or a group where supported. For PTY attach --tty,
Ctrl-] detaches and Ctrl-C reaches the agent. See agent control and
dashboard equivalents.
Board and settings#
| Command | Flags / behavior |
|---|---|
board [group] | -w, --watch; tasks, notes, locks and human requests. |
task add <title...> | -g, --group, -d, --detail, --deps <ids>, -o, --owner, --minutes <n>. Dependency IDs are comma-separated. |
task set <id> | -g, --group, -s, --status, -o, --owner, --summary, --title, -d, --detail, --minutes; empty owner clears it, empty minutes restores group default. |
task ls [group] | List all tasks. |
note <text...> | -g, --group, -k, --kind note|decision|blocker|finding. |
goal [group] [text...] | Show (no text) or set the team's objective; the group defaults to this repo's team. |
budget <group> <usd|off> | Change/remove the cap on billed spending (group set <group> budgetIncludesEstimates=true counts subscription estimates too). |
group show <group> | --json; stored settings (unset keys use their defaults). |
group set <group> <key=value...> | Change group settings; key= clears an override. |
compression [group] [words...] | --json; resolved compression settings and tokens saved per agent and source. With a group and words (on, off, reset, <key> on|off, minTokens|ttlHours <n>), changes that group's setting. compression compare <groupA> <groupB...> [--json] compares team runs (tokens, cost, savings, task outcomes, wall time); see measuring a team run. |
usage [--json] / limits | Show account usage, resets, observation ages and sources. See Account usage. |
limits <group> [--json] / limits --sessions | Show sessions' last usage reports, including stopped sessions labelled stale. |
limits <session> --clear | Retry after changing account/provider settings. |
notify test [group] | Send a test notification with effective targets. |
notify config [group] | Show notification settings with secret webhook URLs masked. |
notify ls [group] | -n, --limit <n> (20); recent delivery results. |
memory [ls] | --repo <path> (default: current directory), -g, --group, --json; the repository's project memory. |
memory add <text...> | -k, --kind decision|finding|note; near-duplicates only raise the existing entry's count. |
memory edit <id> [text...] | Replace an entry's text and/or -k kind. |
memory rm <ids...> / memory clear --yes | Delete entries / all entries of the repository. |
memory release <ids...> | Keep entries quarantined after their remote device was revoked (they are left out of prompts until released). |
task set is a human metadata override; changing status there does not perform the
agent-side commit/integrate workflow. Agents use MCP task_update for completion.
Review and integrate#
| Command | Flags / behavior |
|---|---|
review ls [group] | Pending reviews and reviewers. |
review <group> <task> approve | -m, --message <notes> optional; integrate the reviewed commit. |
review <group> <task> changes -m <notes> | Send a reviewed task back with required notes. |
diff [target] | --stat; session changes or integrated group changes. |
land [group] | Merge into the main checkout; --pr instead pushes and opens/reuses a GitHub PR, with optional --base <branch> and --draft. |
pr checks <group> | Fetch CI results; --watch [minutes] starts background polling (1 minute), --stop-watch stops it. |
learn [group] | Mine what failed and then worked into project learnings (removed groups too, from their archive); preview by default. --all every group (merged per repo), --apply writes, --target <file> (AGENTS.md, CLAUDE or CLAUDE.md; default AGENTS.md). See learnings. |
rm <group> | Stop/remove the group, sessions, worktrees and branches; --keep-branches retains branches. Its lessons are kept: mined learnings and board decisions/findings go to project memory, and its history is archived so nid learn <group> and learn --all still read it. --purge deletes everything, including earlier archives of that group. |
See reviews and landing before deleting an unlanded group.
Daemon and release tooling#
| Command | Behavior |
|---|---|
daemon start | Ensure a background daemon is running. |
daemon run | Run in the foreground. |
daemon stop | Gracefully stop the daemon and agent processes. A daemon that no longer answers is stopped by force, but only when its command line is a nid daemon (including an old one still running from nid.exe.old-* after an update) and it owns the port in daemon.json; otherwise the file is reported as stale and that process is left alone. |
daemon restart | Restart and resume the sessions that were running. |
daemon status | Version, build identity, PID and listener information. Says running old version X when the daemon is older than the CLI (restart it to update) and not responding (exit code 1) when it is running but does not answer. |
daemon logs [-n <lines>] | Daemon log tail (50 lines). |
daemon autostart [on|off|status] | Start the daemon at login (Task Scheduler / launchd / systemd --user); see start at login. |
mcp and update-check are internal transport/updater entry points.
From a source checkout, pnpm build:bin [--target <targets>] [--sign],
pnpm release <version>, and pnpm release:publish [--version <version>] [--draft]
[--dry-run] manage releases. These are package scripts, not nid subcommands;
see releasing.
Remote control (nid rc)#
nid rc shares a team with every phone and browser signed in to your nid.dev account, like
Claude Code's remote control (remote access, section 11).
The first run links the machine: it opens the browser at the accounts service, you sign in
with a passkey and approve the code shown in the terminal, and the daemon then asks your
operating system to verify you once. After that, signing in a phone or browser needs
nothing on the machine; each new device is announced (desktop notification, board note,
the terminal app and every connected device). Your nid.dev account becomes the lock:
whoever signs in to it can steer the shared teams. For per-device pairing instead, set
remote and use nid cloud pair (below).
| Command | Behavior |
|---|---|
rc [team] | Link the machine if needed, then share the team (default: this repository's team). Devices get operate (watch and steer). |
rc --all | Share every team on this machine. |
rc --view | Share read-only. remote caps every share locally; admin is never granted through the account. |
rc --for <duration> | Stop sharing automatically after 30m, 8h, 2d… (1 minute to 30 days). Shares survive a daemon restart. |
rc --no-browser | Print the sign-in URL instead of opening a browser. |
rc --accounts <url> --relay <url> | Another accounts service and relay (self-hosted, development). Defaults: https:/, wss:/; also cloud.accounts/cloud.relay in ~/ and NID/NID_RELAY_URL. A non-nid.dev accounts service needs its signing key in cloud. |
rc --label <name> | The name nid.dev shows for this machine when it is linked. nid.dev sees it (remote access 8.1); the default is the platform (Windows PC, Mac, Linux machine), never the host name. |
rc off [team] | Stop sharing that team, or every team without one (--all). The machine stays linked. |
rc status [--json] | Account, connection, what is shared and until when, the device list's state, connected devices. |
rc devices [--json] | Account and paired devices with role, teams, online state and fingerprint. |
rc devices rm <id> | Revoke a device on this machine; it stays blocked here whatever the account's list says. Remove it on nid.dev too. |
rc unlink | Unlink the machine from the account; account devices stop connecting, paired devices are kept. |
nid rc is refused inside agent sessions, like nid cloud. In the terminal app,
/rc shares the current team (/rc --view, /rc for 8h, /rc all, /rc off [all],
/rc status, /rc devices, /), and the status line shows rc: N devices (devices
connected to shared teams) while anything is shared.
Experimental remote access (strict mode)#
nid rc is the common path. nid cloud is for strict mode (per-device pairing with a
fingerprint comparison on the machine) and self-hosted relays without an accounts service.
All nid cloud commands require --experimental and a plain terminal on the daemon
machine. They refuse nid and recognized vendor agent sessions, even when
NID. The daemon performs OS user verification for sensitive
changes; a CLI flag cannot assert that verification succeeded.
| Command | Purpose |
|---|---|
cloud login --relay <wss-url> | Print a browser device-code login URL, wait for account approval, then verify the local user and link the daemon. Round A includes the loopback development account service. |
cloud logout | Unlink the relay account. |
cloud status | Show connection, verifier, devices, pairing and key-rotation status. |
cloud on / cloud off | Enable or disable the outbound connection. |
cloud relay <wss-url> | Change the relay after local user verification. |
cloud pair [--role view|operate|admin] [--groups a,b] | Check the console, display a QR and URL, compare device fingerprints and confirm locally. Default role is view; --groups '*' permits all groups. |
cloud pair --code | Show the 80-bit code in four groups of four. |
cloud no-verifier | Persist a confirmed local decision that this machine has no OS verifier; refused if one was ever observed. Requires an interactive plain terminal. |
cloud pair --cancel | Explicitly cancel the current pairing offer and announce cancellation. |
cloud pair --show | Show an existing offer created by an admin device; use its matching --console origin. |
cloud devices | List devices, roles, scopes and verification methods. |
cloud devices rm <id> | Revoke a device and report cleanup. |
cloud devices rm --all-others [--except <id>] | Revoke all devices except the named device. |
cloud devices role <id> <role> | Change a role; raising it requires local verification. |
cloud devices scope <id> <groups> | Set comma-separated groups or *; widening requires verification. |
cloud devices rename <id> <label> | Rename a device. |
cloud rotate-key [--compromised] | Rotate daemon identity; compromised mode invalidates pairings immediately. |
cloud console-check [--console <origin>] | Verify the signed manifest, every asset and the signed transparency log. |
Append --experimental to each command, or put it after nid or cloud.
For a self-hosted relay without accounts, set NID in your terminal's
environment and run nid cloud login --experimental --relay <wss-url>. The CLI sends
the secret only to the local daemon, which verifies the user and stores it as the
connector credential. It does not start a browser login. Never put the secret in a
command-line argument; clear the environment variable after linking. With no secret
set, login uses the account device-code flow described above.
Pairing requires an interactive terminal: secrets appear on its alternate screen
and are cleared on completion, expiry or interruption. Confirm the fingerprint
shown on the phone, not only its chosen label. Cancel with Ctrl+C.
For a local unsigned development console, use --console http:/ with pair or console-check. The bypass never applies to
nid.dev or its subdomains. Production self-hosted consoles put their Ed25519
public keys in the local cloud array in ~/.
cloud.console selects the default console and cloud.relay selects the login
relay. cloud locally caps hosted-console devices. No hosted
release key has been provisioned for round A, so hosted checks fail closed.
After explicitly recording nid cloud no-verifier --experimental on a machine where no OS verifier has ever been observed, pair --no-user-verification --role view is the
explicit restricted fallback. It cannot grant operate/admin. Login has the matching
restricted --no-user-verification option. These options do not bypass a rejected
prompt on a machine with an available verifier. See remote access, appendix D
for platform prerequisites, the release-signing format and the manual OS-prompt check.