Commands Reference

All commands are run through ndx (or n-dx). The directory argument [dir] defaults to . (current directory).

Setup

Command	Description
ndx init [dir]	Initialize a project for n-dx
ndx migrate-layout [dir]	Move an existing project's state into .ndx/
ndx migrate [dir]	Run every migration step the project still needs: the layout move into .ndx/, the prd.md / prd.json conversion, then the v1 → v2 plan and apply. Steps already done are skipped (--dry-run, --rules-only)
ndx migrate --plan [dir]	Plan the PRD's v1 → v2 migration and write it out for review
ndx migrate --apply [dir]	Apply the reviewed migration plan (--plan=<path>, --dry-run)
ndx config [key] [value]	View or edit settings
ndx which	Show which n-dx is running: version, path, install kind, git
ndx trust [status|accept|revoke] [dir]	Review or accept the execution config this checkout ships
ndx extensions <list|add|remove|enable|disable|info|doctor>	Install, approve, disable, remove and check extensions (--json, --yes, --purge)

Analyze

Command	Description
ndx analyze [dir]	Run codebase analysis
ndx iso [dir]	Render a standalone isometric architecture map
ndx recommend [dir]	Show or accept findings as PRD items

Plan

Command	Description
ndx plan [dir]	Analyze codebase and generate PRD proposals
ndx add "<desc>" [dir]	Add a change to the PRD from natural language

Product layer and changes

The PRD is the product's requirements (the product layer) plus the changes being made to them (the change layer); see The PRD. These rex commands work on a v2 PRD (.ndx/rex/product/ and .ndx/rex/changes/) and refuse a v1 one. Run them as rex <command> or ndx rex <command>.

Command	Description
rex product show [<node>] [dir]	The areas, capabilities and constraints with computed status and health; with a node, its statement, capability criteria and changes
rex product edit <node> [dir]	Edit a capability's or constraint's statement (--statement) or capability criteria (--capability-criterion="<id>: <text>"); --editorial for wording only
rex change place <change> [dir]	Without --target, the shortlist of places a change could go; with --target=<node> --relation=touches|amends, record it; with --propose --type=capability|constraint --under=<area> --title="…", propose a new node when nothing fits
rex change apply <change> [dir]	Apply a change's amendments to the product layer, as a steward
rex release stamp <version> [dir]	Stamp shippedIn on the changes a release ships
rex codeowners [dir]	Write the host's code-owner files from the stewards lists (opt-in)

Execute

Command	Description
ndx work [dir]	Run next task autonomously
ndx self-heal [N] [dir]	Iterative improvement loop (N cycles)

Manage

Command	Description
ndx status [dir]	Show PRD status tree
ndx next [dir]	Print next actionable task
ndx tree [dir]	Show the full PRD tree with color-coded status
ndx tree-diff [dir]	Compare two PRD trees (commits, or a worktree against its anchor)
ndx claim list|release [dir]	Inspect and free cross-worktree task claims
ndx log <event> [dir]	Append an execution-log entry (non-MCP route to append_log)
ndx prd export|import	Carry the PRD between machines as a JSON bundle, or export a narrative document
ndx report [dir]	Generate a JSON health report
ndx update <id> [dir]	Update item status, priority, or title
ndx remove <id> [dir]	Remove an item and its children
ndx move <id> [dir]	Reparent an item under a new parent
ndx validate [dir]	Check PRD integrity
ndx fix [dir]	Auto-fix common PRD issues
ndx health [dir]	Show PRD structure health score
ndx verify [dir]	Run acceptance criteria tests
ndx reshape [dir]	LLM-powered PRD restructuring
ndx reorganize [dir]	Detect and fix structural issues
ndx prune [dir]	Remove completed subtrees
ndx readiness [dir]	Score SDLC readiness for autonomous agent work (--json)
ndx reset [dir]	Remove analysis data and start fresh
ndx show <run-id> [dir]	Show details of an agent run
ndx usage [dir]	Token usage analytics
ndx ci [dir]	Run analysis pipeline and validate PRD health
ndx auth [dir]	Check and configure LLM provider credentials

Serve

Command	Description
ndx start [dir]	Start dashboard + MCP server
ndx dev [dir]	Start dev server with live reload
ndx refresh [dir]	Refresh dashboard artifacts
ndx export [dir]	Export static deployable dashboard
ndx web [dir]	Dashboard server control (lower-level counterpart to ndx start)
ndx graview <emit|check|describe|serve|mcp> [dir]	Project the PRD, analysis and runs into Graview and drive the graview CLI on the result

Try it out

Command	Description
ndx install-sample [dir]	Install a sandboxed sample app with a pre-populated PRD
ndx destroy-sample [dir]	Remove the sample app and its PRD items

Cross-vendor review

Command	Description
ndx pair-programming "<desc>" [dir]	Run two vendors against one task — primary implements, reviewer checks
ndx bicker [dir]	Adversarial cross-vendor review of a change

---

Command Details

init

ndx init .                       # interactive provider selection, both assistants
ndx init --provider=claude .     # skip prompt, use Claude as LLM
ndx init --provider=codex .      # skip prompt, use Codex as LLM
ndx init --claude-only .         # provision only Claude surfaces
ndx init --codex-only .          # provision only Codex surfaces
ndx init --assistants=claude .   # equivalent to --claude-only
ndx init --no-codex .            # skip Codex provisioning
ndx init --git .                 # also create a git repository (answers the preflight prompt)
ndx init --no-git .              # never create one

Initializes the project: creates analysis metadata (.sourcevision/), PRD storage (.rex/, holding an empty v2 PRD; an existing v1 PRD keeps its layout until ndx migrate), agent configuration (.hench/), and assistant-specific artifacts. By default both Claude and Codex surfaces are provisioned.

When the directory is not inside a git repository, init offers to create one — n-dx records autonomous work as commits, so without a repository auto-commit, pair programming, and the hench run loop stay disabled. That prompt needs a TTY: scripted runs and the dashboard's setup wizard answer it with --git or --no-git instead. A repository created this way also gets a chore: n-dx init baseline commit, so the working tree is clean straight out of init.

On re-run, detects existing assistant surfaces and narrows provisioning to match. If only Claude artifacts exist, Codex is skipped (and vice versa) unless you explicitly pass an assistant flag.

Generated assistant artifacts:

Claude	Codex
CLAUDE.md	AGENTS.md
.claude/skills/*/SKILL.md	.agents/skills/*/SKILL.md
.claude/settings.local.json	.codex/config.toml
MCP servers via tracked .mcp.json	MCP servers via .codex/config.toml

analyze

ndx analyze .                # standard analysis
ndx analyze --deep .         # full multi-pass analysis
ndx analyze --lite .         # fast single-pass (skips LLM enrichment)

Scans the codebase: file inventory, import graph, zone detection (Louvain community detection), component catalog. Results drive recommendations and planning.

recommend

ndx recommend .                      # show current findings
ndx recommend --accept .             # add all to PRD
ndx recommend --actionable-only .    # filter to concrete problems only
ndx recommend --acknowledge=1,2 .    # skip specific findings
ndx recommend --acknowledge-completed .  # acknowledge completed findings

add

ndx add "Add SSO support with Google and Okta" .
ndx add "Request A" "Request B" .     # multiple requests
ndx add --file=ideas.txt .            # import from file

Each description becomes one change in the Inbox, with no LLM call. The output names the change and the rules' suggested placement, which rex change place records. --criterion="…" (repeatable) sets the change's acceptance criteria, its "done when"; a capability's capability criteria are edited with rex product edit, never here.

v1 projects

On a v1 PRD (.rex/prd_tree/, a project that has not yet run ndx migrate), ndx add uses an LLM to decompose the descriptions into a proposal of epics, features and tasks, detects duplicates, and offers merge, cancel or proceed.

plan

ndx plan .                  # interactive: analyze + propose
ndx plan --accept .         # auto-accept proposals
ndx plan --guided .         # step-by-step guided mode
ndx plan --file=spec.md .   # import from document (skips analysis)

Combines analysis and proposal generation in one step. Use analyze + recommend separately for more control.

work

ndx work .                             # interactive task selection
ndx work --auto .                      # highest-priority task
ndx work --auto --iterations=4 .       # run 4 tasks sequentially
ndx work --task=abc123 .               # specific task
ndx work --epic="Auth System" --auto . # scope to one top-level item
ndx work --dry-run .                   # preview without executing
ndx work --model=claude-opus-5-5 .        # override model
ndx work --auto --loop .               # run continuously until done

Task selection modes

By default on an interactive terminal, ndx work presents a menu to choose which task to work on. The --auto flag skips this and auto-selects the highest-priority pending task instead. Use --task=<id> to target a specific task directly (this overrides both interactive and auto selection).

Flag	Behavior
(none, TTY)	Interactive menu — pick a task from the list
--auto	Auto-select highest-priority pending task
--task=<id>	Run a specific task by ID

Running multiple tasks

--iterations=N runs N tasks back-to-back, auto-selecting the next highest-priority task after each one completes. Defaults to 1. Stuck detection skips tasks that have failed repeatedly (default: 3 consecutive failures) so iterations don't get stuck on the same broken task.

--loop runs tasks continuously until all tasks are complete or you hit Ctrl+C. Implies auto-selection. Use --loop-pause=<ms> to add a delay between iterations.

Scoping

--epic=<name-or-id> restricts task selection (both interactive and auto) to the tasks under one top-level item, matched by title substring or id. Combine with --auto or --iterations to work through it sequentially. The flag keeps its v1 name: on a v1 PRD the top-level items are epics.

Other flags

Flag	Description
--dry-run	Build and display the brief without executing
--model=<model>	Override the LLM model for this run
--priority=<level>	Override task scheduling priority (critical, high, medium, low)

self-heal

ndx self-heal 3 .           # 3 improvement cycles
ndx self-heal .             # default: 1 cycle

Each cycle: analyze → recommend (actionable-only) → work → acknowledge completed.

start

ndx start .                 # foreground on port 3117
ndx start --port=8080 .     # custom port
ndx start --background .    # daemon mode
ndx start status .          # check if running
ndx start stop .            # stop daemon

ndx start registers the repository with the per-user hub, whose chooser at http://localhost:3117/hub lists every registered project. New project there creates one that does not exist yet: give it a folder name and the directory to put it in, check the absolute path it previews — resolved by the server as you type, so .. and a relative parent show as what they really are — and it creates the folder, registers it, and opens the same setup wizard an empty folder gets (assistants, LLM vendor, and whether to create a git repository). A folder that already has content is refused, with a pointer to ndx start for registering an existing project instead.

graview

ndx graview emit .          # write document.json and snapshot.json under the graview dir
ndx graview check .         # re-emit, then graview check on the declaration
ndx graview describe .      # re-emit, then graview describe: the places and acts the document declares
ndx graview serve .         # re-emit, then the product face (@n-dx/graview-face) on http://localhost:5188
ndx graview mcp .           # re-emit, then graview mcp over stdio on the snapshot
ndx graview info .          # where the projection, the graview binary, the face and rex's MCP endpoint are
ndx graview emit --no-files .  # leave file nodes out

ndx graview projects the PRD tree, sourcevision's zones and components and hench's runs into a Graview declaration and a {nodes, edges} snapshot under the layout's graview dir (.graview/, or .ndx/graview/ on the .ndx layout), then spawns the graview CLI on them. No @graview/* package is installed with n-dx: the binary is found through graview.bin in the project config, $NDX_GRAVIEW_BIN, PATH, the installed @n-dx/graview-face's own graview, then npx -y graview@<pinned>. serve runs the separately published @n-dx/graview-face when it is installed or beside the adapter in the monorepo; when the repository is registered with the hub (ndx start .), the face writes changes and tasks back to rex through its MCP endpoint. See Graview projection.

status

ndx status .                # PRD tree
ndx status --format=json .  # machine-readable
ndx status --all .          # include completed items

config

ndx config .                          # show all settings
ndx config llm.vendor claude .        # set vendor
ndx config llm.claude.api_key KEY .   # set API key
ndx config hench.provider api .       # API mode
ndx config --json .                   # JSON output

---

Skills Reference

The workflow skills installed by ndx init are the assistant-session equivalents of the CLI commands above. For per-skill documentation, trigger conditions, and customization guidance, see the Skills Reference.

Advanced: Direct Tool Access

For power users, individual tools can be accessed directly:

ndx rex <command> [args]          # PRD management
ndx hench <command> [args]        # Agent operations
ndx sourcevision <command> [args] # Analysis engine
ndx sv <command> [args]           # Alias for sourcevision

These are also available as standalone commands (rex, hench, sourcevision, sv) after installation.