CLI Commands

Every subcommand exposed by np-tools.cjs, mirrored from bin/np-tools/_commands.cjs (the canonical registry).

Dispatch has two layers:

• init <workflow> — orchestrator workflows. Calls a registered handler in bin/np-tools/<name>.cjs (plan-milestone, execute-milestone, discuss-phase, new-project, …). An unknown init workflow returns unknown-init-workflow with exit code 1.
• Top-level commands — utility and leaf commands (commit-task, checkpoint, metrics, doctor, …).

Output is JSON; payloads above 16 KB are spilled to .nubos-pilot/.tmp/init-<workflow>-<pid>-<rand>.json and the path emitted as @file:<path>.

Commands by category

Planning

Command	Description
agent-skills	Print agent_skills config for a given subagent
archive-project	Move current .nubos-pilot/ project to archive/<slug>-<YYYYMMDD>/ (status|do|list|read)
discuss-phase	Adaptive milestone-context interview (writes M<NNN>-CONTEXT.md)
discuss-project	Adaptive project-context interview (writes PROJECT.md decisions)
new-milestone	Append a new milestone (M<NNN>) to an existing project
new-project	Greenfield project init (PROJECT.md + REQUIREMENTS.md + M001 milestone)
phase-meta	Read roadmap.yaml phase fields as JSON (supports --field NAME and --length for arrays)
plan-lint	Mechanical Trust-Layer linter for PLAN.md (verify-command + parallel-race + over-specification). ADR-0019
plan-milestone	Plan a milestone: scaffolds slices + tasks
propose-milestones	Re-plan all not-yet-done milestones: AI proposes add/update/remove from PROJECT.md + REQUIREMENTS.md
research-phase	Milestone-level research (WebFetch + MCP; offline fallback)
researcher-reconcile	Researcher-swarm reconciliation (ADR-0018). Verbs: parse-spawn --file | prepare <N> | gate <N>. Reads per-spawn outputs, applies reasoning-trace classification, surfaces contested decisions, hard-gates on agreement_score / contested_count.
update-phase-meta	Update roadmap.yaml phase fields (name/goal/requirements/success_criteria) via JSON patch

Execution

Command	Description
add-tests	Persist VERIFICATION Pass-cases as node:test UAT (Sentinel-preserving)
checkpoint	Per-task crash-safety checkpoint CRUD (start/transition/touch/show)
commit-task	Atomic per-task git commit via lib/git.cjs
execute-milestone	Wave-based milestone execution — slice by slice, tasks parallel within a slice
learning-log	Persist a learning to the local store (or MCP adapter when configured)
loop-audit-tool-use	Record/read the tool-use audit per spawn (Completeness Rule 9 mechanical check)
loop-evaluate	Run evaluateLoop over critic outputs JSON; emit next_action + findings + routing
loop-preflight	Per-task pre-flight cache lookup (ADR-0010 Step 1) — short-circuits the Researcher-Schwarm on hit
loop-run-round	Drive the per-task Nubosloop state machine — phases: preflight | post-executor | post-critics | commit | stuck
loop-state-read	Read the per-task Nubosloop state from the checkpoint (round, last_action, findings)
loop-state-record	Atomically merge a partial Nubosloop state update into the task checkpoint
loop-stuck	Mark a task as stuck (writes loop-state + flips checkpoint status to stuck)
park	Mark task status parked (lifecycle CRUD)
pause-work	Stamp STATE.session.stopped_at + resume_file for explicit handoff
reset-slice	Discard in-flight task: restore working tree from HEAD, drop checkpoint, clear STATE.current_task
resume-work	Classify session state (resume | orphan | clean) from STATE + checkpoints
skip	Mark task status skipped (lifecycle CRUD)
spawn-headless	Spawn an agent as a headless claude -p subprocess (ADR-0010 §L6); writes stdout to --output-path and returns exit code
undo	Revert every task commit of a milestone or slice via git revert (no history rewrite)
undo-task	Revert a single task commit and reset task status to pending
unpark	Return a parked task to pending (lifecycle CRUD)
verify-work	Two-pass goal-backward verification (milestone-level VERIFICATION.md)
worktree-create	Create an isolated git worktree for a slice (branch np/<mid>-<sid> off current HEAD) under .nubos-pilot/worktrees/
worktree-ff-merge	Fast-forward merge a slice branch back to its base (fails hard on non-FF)
worktree-list	List all nubos-pilot-managed slice worktrees (np/<mid>-<sid> only) as JSON
worktree-remove	Remove a slice worktree + delete its branch (--force / --keep-branch)

Review

Command	Description
close-project	Aggregate verification of every milestone; writes PROJECT-SUMMARY.md + sets project_status=completed
output-lint	Mechanical output-artifact linter (frontmatter + body + cross-field invariants). Verbs: check | prompt | list. Schemas in lib/schemas/. Hard-gates verify-work, validate-phase. ADR-0017

Capture

Command	Description
add-todo	Capture a pending todo to .nubos-pilot/todos/pending/ + increment STATE count
handoff-list	List handoffs (JSON array); filter with --for AGENT, --milestone M<NNN>, --status STATUS, --global
handoff-read	Read a single handoff by id (returns frontmatter + body as JSON)
handoff-status	Update a handoff status (open|read|acted|archived)
handoff-write	Write an agent-to-agent handoff note (milestone-scoped by default, global without --milestone)
memory-add	Add a single record to vector memory (--type, --title, --body, optional --tags / --provenance / --phase / --id)
memory-index	Bulk-index records into vector memory (--records JSON or --records-file JSONL). Opt-in via memory.enabled=true. ADR-0014
messages-archive	Move an inbox message to archive/; refuses request+expects_reply without prior response
messages-inbox	List unread messages addressed to an agent (filterable by --kind, --since, --task)
messages-send	Send addressed inter-agent message (request|response|notify) to .nubos-pilot/messages/inbox/<to>/. ADR-0015
messages-thread	Print full reply-chain for a message id (causal order)
state-incr	Increment a whitelisted STATE.md counter (e.g. pending_todos) under withFileLock

Install

Command	Description
doctor	12-check install-integrity scan (--fix for auto-safe fixes)
scan-codebase	Initial deep codebase inventory → .nubos-pilot/codebase/ skill docs
update-docs	Refresh stale module docs after code changes
workspace-scan	Scan a workspace and emit inventory JSON (full result or --summary shape for /np:new-project)

Utility

Command	Description
askuser	Capability-layer prompt wrapper (reads spec JSON, returns chosen label)
commit	Atomic git commit wrapper with gitignore-guard
config-get	Read value from .nubos-pilot/config.json by dotted key path
context-stats	Aggregated context-budget stats (file counts + bytes per group, knowledge-index size)
dashboard	One-shot console dashboard of milestones, slices, and tasks. Read-only; flags: --json, --no-color
detect-runtime	Print detected runtime id (claude, codex, gemini, …) — reads config.json ∨ env ∨ default
generate-slug	Slugify text via lib/layout.cjs.slugify
help	List available commands
init	Dispatcher init payload for workflows
knowledge-index	Build BM25-light index over .nubos-pilot/**/*.md → .nubos-pilot/state/knowledge-index.json
knowledge-search	Query the knowledge index; returns top-N JSON hits (rel_path + lines + score + preview). Pass --task <id> inside a Nubosloop task to record Rule 9 audit evidence
knowledge-stats	Print knowledge-index size + grouping (auto-builds if missing)
lang-directive	Print workflow language directive from config.response_language (SSOT)
learning-list	List learnings sorted by occurrence (most-used first)
learning-match	Query the learnings store for cached patterns matching a free-text query
loop-metrics	Aggregate Nubosloop telemetry across all checkpoints (commits, stuck, route distribution)
memory-query	Query vector memory by text; returns top-k JSON hits with score + record. Filter by --type, --phase, --tags
memory-rebuild	Force full re-embed from records.jsonl; required after embedding-model change. ADR-0014
memory-stats	Print vector-memory stats (count, dim, model, schema_version, created_at)
metrics	Record JSONL metrics entry (record | now | start-timestamp | end-timestamp)
render-template	Render a shipped template by name with --vars JSON (or --vars-file PATH)
render-todo	Render slice TODO.md rollup (checkbox view of task statuses) for a slice full-id
resolve-model	Resolve agent/tier to model alias or id (Tier×Profile matrix)
session-aggregate	Aggregate session metrics under withFileLock; reads pointer .last-session unless --since overrides
session-pointer-write	Atomic write of .nubos-pilot/reports/.last-session under withFileLock (ISO-8601 UTC)
session-snapshot-read	Print last session snapshot as JSON
session-snapshot-write	Capture session snapshot (current_task + recent commits + open handoffs) for resume
state	Print the current project state snapshot
state-dir	Print project-state directory (.nubos-pilot) or a validated subdir via --subdir NAME
stats	Aggregated project stats — json | bar | markdown (markdown labels follow config.response_language)
template-path	Print absolute path to a package-shipped template by name (e.g. VALIDATION, milestone/CONTEXT)
text-mode	Print whether text mode is active (config.workflow.text_mode ∨ CLAUDECODE)
thread-resume	Bump a thread markdown on resume (status OPEN→IN_PROGRESS, refresh last_resumed) via atomic write

The tables above are regenerated from bin/np-tools/_commands.cjs by scripts/generate-docs.cjs. To add a command, append an entry to that registry; the doc table picks it up on the next run.

Registry descriptions are one-line summaries. Where a command needs more detail, the dedicated reference or workflow page is authoritative. For example, np:doctor lists all 12 integrity checks.

User-facing workflow aliases

Three slash-commands preserve older naming for continuity. They dispatch to milestone-scoped init commands:

User-facing	Delegates to	Notes
/np:plan-phase <N>	init plan-milestone init <N> + scaffolder	"phase" = milestone in the command name
/np:execute-phase <N> [--verify-work]	init execute-milestone init <N> [--verify-work] + per-task dispatch	slice-by-slice, tasks parallel within slice; --verify-work chains /np:verify-work <N> on success
/np:validate-phase <N>	Nyquist auditor → M<NNN>-VALIDATION.md
/np:close-project	init close-project + askuser blocker gate	project-level aggregate verification; writes PROJECT-SUMMARY.md and flips project_status: completed
/np:architect-phase <N>	spawns np-architect → M<NNN>-ARCHITECTURE.md	optional, between research and planning
/np:knowledge "<query>"	wraps knowledge-index + knowledge-search	local full-text search over project markdown
/np:context-stats	wraps context-stats	localized markdown snapshot of the knowledge index