Command reference¶
Live CLI is authoritative: nw --help and nw <command> --help. This page is a
curated index of top-level commands (synced by test to nw --help). It does not
duplicate every flag.
Bare nw (no subcommand) prints the today + this-week dashboard. Add --split for the
Claude-generating vs your-turn diagnostic.
Index¶
| Command | Purpose | See also |
|---|---|---|
(bare) nw |
Dashboard: today + this week | Report |
add |
Capture a new org task | Tasks |
agenda |
Tasks by SCHEDULED/DEADLINE (+ overdue) | Tasks |
backups |
Org-file backup retention: prune (dry run unless --yes) |
Tasks, Ideas |
campaign |
Campaign state, ledger and notes (agentic loop) | Agentic loop |
completion |
Generate / install shell completion | Completion |
dashboard |
Read-only dashboard snapshot of the agentic queue: dashboard snapshot [--json] prints the nw.dashboard.v1 document (health, counts, spend, needs-you, open escalations and human-owned parks) as a text summary or JSON; builds in-process, needs no server, tailscale or token, and writes nothing (SPEC-0401) |
Agentic loop |
doctor |
Read-only, offline install health check: tools, config, skills, completion, agentic queue, projects; --fix-hints, --json (nw.doctor.v1), --project NAME; exit 1 on any fail (SPEC-0349) |
Getting started |
digest |
Hours joined to org tasks by JIRA key | Report |
done |
Mark a task done | Tasks |
export |
Save date/topic/hours/facets dataset | Report |
hub |
Read-only triage JSON (ideas + specs + tasks) | Hub |
idea |
Capture or enrich ideas (subcommands below) | Ideas |
ideas |
List / filter / query / tree ideas | Ideas |
ingest-meetings |
Filter a raw calendar JSON dump | Meetings |
mailbox |
Conductor ↔ steward messages (agentic loop) | Agentic loop |
escalations |
Questions escalated to the human: list [--all] [--json] / show / answer ID (--choose\|--text\|--waive\|--attest) [--yes] / withdraw (agentic loop) |
Agentic loop |
gate |
Standalone remote gate jobs on worker boxes, no campaign: run [--project P] [--worktree PATH\|--branch B] [--base REF] [--tier loop\|close\|all] [--cmd CMD ...] [--by WHO] [--wait\|--detach] [--wait-s S] [--json] (exit 0 green / 1 red / 2 cannot start / 3 box unavailable / 4 transport), status ID [--json] (nw.gatejob.v1), logs ID [GATE], cancel ID, list; config agentic.gate_jobs.{enabled,max_per_requester,max_slots,retention_days} (SPEC-0381) |
Agentic loop |
herdr |
herdr sidebar tokens + notifications for the queue: watch [--interval S] [--conductor-pane ID] [--workspace ID] [--once] [--run-panes] [--run-pane-linger S], status [--json]; the conductor's follower starts watch by itself inside herdr (agentic.herdr.auto_watch, log <data_dir>/agentic/conductor/herdr_watch.log); a no-op outside herdr; --run-panes opens a tab per campaign with a running run, named after the work (SPEC-0361/0363/0365/0366, see docs/herdr.md in the repo) |
Agentic loop |
map |
Assign facets to a base topic | Report |
migrate-from-wt |
One-time move of a pre-rename wt install to nightwright's config/data dirs (dry run unless --yes, SPEC-0330) |
Bootstrap |
next |
Next-step hints for open ideas | Ideas |
override |
Time-scoped reclassification | Report |
personas |
Agentic persona registry: list / show NAME / validate [--project NAME] [--json] over the builtin, user (config dir personas/) and project (main-checkout .nw/personas/) layers, with each definition's origin file, and for a declared one its run settings, required / when and template sha256; validate exits 1 on any problem (SPEC-0370, SPEC-0371, SPEC-0394) |
Agentic loop |
profiles |
Agentic workflow profiles: list / show (with sources) / check | Agentic loop |
projects |
List / register outbox + research targets | Projects |
queue |
Agentic work queue: add / list / watch / run / park / resume, conductor tooling (subcommands below) | Agentic loop |
refresh-meetings |
Pull Outlook meetings into meetings.jsonl | Meetings |
release-archive |
Pack git HEAD + ideas slice tarball | Release archive |
report |
Per-topic hours | Report, Track time |
review |
Segment timeline / unclassified / orphans | Report |
serve |
Coordinator side of pull workers: serve --jobs [--bind ADDR:PORT] [--tls-cert F --tls-key F [--client-ca F]] serves the pull-worker job API (lease, bundle, frames, result bundle, heartbeat) over HTTP(S); default bind 127.0.0.1:8790; without TLS only loopback or Tailscale binds are allowed; --client-ca requires a client certificate whose CN is the worker's name (SPEC-0334, see "Pull workers" in docs/WORKFLOW.md in the repo); serve --dashboard [--bind ADDR:PORT] serves the read-only dashboard (GET /api/snapshot, strong ETag = rev, 304 on If-None-Match) on loopback only (default 127.0.0.1:8791), with a per-host bearer token in <data_dir>/agentic/dashboard/local.token, Host/Origin checks, an audit log of refusals and a runtime record server.json; any other non-loopback bind and any TLS flag is refused with exit 2 (SPEC-0414). --bind tailscale[:PORT] resolves to this host's own tailnet address (tailscale ip, the only tailscale form run; SPEC-0416): another machine's tailnet address is refused as foreign, and serving on the tailnet is still refused with exit 2 until the identity gate lands (the message names it and the loopback alternative); a host with no tailnet address (tailscale missing, logged out or stopped), including an explicit address in the tailnet ranges, exits 3 with a message naming tailscale up. Exactly one of --jobs and --dashboard is required |
Agentic loop |
sheet |
Sheet-sync plan/record (JSON-only) | Sheet |
skills |
Install/list agent workflow skills | Skills |
snapshot |
Archive past days to history.jsonl | Track time |
spec |
Spec scaffold / generate / export / verify | Idea → ship, Outbound |
state |
Set a task's TODO state | Tasks |
tasks |
List org tasks | Tasks |
topics |
Discovered base topics + facets | Report |
tui |
Interactive desk (optional tui extra): tabs ideas / hub / queue / events / mailbox (--tab), campaign screen (--campaign) |
Desk |
worker |
Remote gate worker, run on the worker host: gate-job / have / gc / info / ssh-command (SPEC-0336); serve --enrol BLOB \| --config F runs a pull worker that dials the coordinator's nw serve --jobs (SPEC-0334) |
Agentic loop |
workers |
Coordinator's worker registry (<agentic_dir>/workers.json), distinct from nw worker which runs on the worker host: add NAME --ssh DEST [--slots N] [--nw CMD] [--no-check] / add NAME --pull [--kinds ...] [--url URL] prints a one-time enrolment blob for a pull worker / token NAME --rotate replaces its credential (SPEC-0334) / list [--json] / check [NAME] [--json] / set NAME [--slots N] [--kinds K] [--persona-slots N] (SPEC-0344; --slots 1..16 changes gate slots in place: raising applies on the next tick, lowering never kills a held slot, which drains naturally; SPEC-0390) / on NAME / off NAME / clear-cooldown NAME (cooldown only; SPEC-0387) / rm NAME (SPEC-0337) / update NAME [--force] [--dry-run] upgrades a worker to this checkout's build over its restricted key (SPEC-0385); update NAME --when-idle drains it and lets the queue update it once idle, then resume (SPEC-0386; agentic.workers.update_drain_timeout_h default 6, agentic.workers.auto_update default false). A job-level error from a live worker (ENOSPC, a bug in a gate run) no longer cools the worker down: the job is retried on another slot; a worker below agentic.workers.min_free_gb (default 5) refuses new jobs (SPEC-0387). Disk guard (SPEC-0388): a job whose process is gone has its tree/tmp/out removed by the worker after agentic.workers.reap_lost_after_min (default 10; caches and repos/ are never touched); a running job whose host falls below agentic.workers.abort_free_gb (default 2, 0 = off) kills the largest job with a job_error frame; nw worker jobs [--json] shows per-job size_bytes; update fails before uploading unless the worker has 3x the wheel free |
Agentic loop |
Nested groups (high level)¶
nw idea …¶
Capture (nw idea "…"), show, summary, log, questions, mark-explored,
clock-in / clock-out, state, project, tags, kind, priority, workstream,
retitle, close, ext, plus maintenance helpers (normalize-logs, …). Full list:
nw idea --help.
nw spec …¶
new, generate, verify, status, export, pull-status, pull-clock, sweep, reconcile,
schemes, seed-children, fit-log, postmortem, plus the review and numbering helpers:
review (reviewer persona; --show, --profile, --path), reviews (latest stored review
of every spec), reserve / reservations / release (SPEC-number reservations visible
across branches and worktrees). Full list: nw spec --help.
nw projects …¶
list (the default), add, rename OLD NEW (dry run unless --yes), and config / init
for the per-project .nw/project.yaml (Agentic loop).
nw queue …¶
add (specs or IDEA-NNN), list, watch, run, tick, stop, park, resume,
abandon, prioritize, backlog, merge, gc, gates, gate-slots, sweep-prs, plus
the conductor tooling: events, followers, wakeups, runner-log, decision,
decisions, escalate, conduct-status, conductor-brief, conductor-cost,
conductor-session, conductor-launch, steward-launch and mvp-report. Full list:
nw queue --help.
nw dashboard …¶
snapshot (text summary) and snapshot --json (the nw.dashboard.v1 document) build the
dashboard view in-process from the queue's read-only payload builders; nothing is written
(SPEC-0401). Full list: nw dashboard --help.
nw sheet … / nw skills … / nw completion … / nw campaign …¶
Subcommands via nw <group> --help.
Date scopes¶
Shared by report, review, agenda, digest, refresh-meetings:
nw report # today
nw report --week # this week
nw report 2026-06-01 # that day
nw report -w 2026-06-01 # week containing that date
nw report --last 7