Command reference
This reference lists the public commands most users need. Hidden recovery and maintenance commands still exist for compatibility, but the compact surface below is the stable entry point for running workflows, inspecting results, and operating the dashboard.
nax init
nax init [OPTIONS]| Flag | Purpose |
|---|---|
--project-root <path> | Initialize a specific project root. |
--repo <owner/name> | GitHub repository, otherwise resolved with gh repo view. |
--site-id <id> | Link to an existing Netlify site id. |
--site-name <name> | Link to or create a Netlify project by name. |
--create | Create a Netlify project when none is linked. |
--dry | Preview setup without writing files or secrets. |
--github-actions | Enable GitHub Actions transport setup. |
nax run
nax run [flow] [OPTIONS]
nax run agent <claude|codex|gemini|opencode> [prompt...] [OPTIONS]| Flag | Purpose |
|---|---|
--branch <branch-or-pr> | Branch or PR selector such as fix/auth or #123. |
--context <text> | Additional context appended to each prompt. |
--context-file <path> | Additional context read from disk. |
--agents <instances> | Select comma-separated or repeated provider[:model[:effort]] instances. |
--models <agent=model> | Assign a real model ID to a provider. Repeat for more providers. |
--efforts <agent=effort> | Assign reasoning effort to a provider. Repeat for more providers. |
--step <id> | Run only one step. |
--from-step <id> | Run from a step through the end. |
--transport <kind> | auto, github, github-actions, or netlify-api. |
--dry | Preview without creating issues, jobs, or artifacts. |
--force | Skip confirmation prompts. |
--retry [run-id] | Retry one failed Netlify API agent run and continue. |
Advanced workflow overrides use --step-agents <step=agents>,
--step-models <step:agent=model>, and
--step-efforts <step:agent=effort>. Direct single-agent runs use
--model <id> and --effort <level>.
Use --agents for repeated providers, bake-offs, and effort sweeps:
nax run review \
--agents claude:claude-opus-5:low \
--agents claude:claude-opus-5:high \
--agents gemini:latest:highBare values such as --agents claude,codex remain Auto on the wire. The
latest and default aliases pin the catalog default at launch. Legacy
--models and --efforts mappings remain available only when each provider is
unambiguous; use exact instance specs for repeated providers.
auto for a model or effort means omission on the wire. Pinned model or
effort settings make --transport auto select netlify-api. Explicit
--transport github rejects pinned settings because the GitHub Action only
supports provider selection.
Retry accepts --instance <agent:model:effort> to select one failed tuple.
The older --agent <provider> selector remains valid only when that provider
has one failed instance in the step.
nax handoff
nax handoff [run-id] [OPTIONS]| Flag | Purpose |
|---|---|
--workflow <id> | Workflow artifact id. |
--runner <id> | Agent runner id. |
--session <id> | Agent session id. |
-c, --copy | Copy selected summary to the clipboard and exit. |
--open | Open the selected summary file. |
--agent <name> | Start a fresh handoff run with one agent. |
--flow <id> | Run a workflow using the selected summary as context. |
nax list
nax list --verbose
nax list --jsonnax costs
nax costs
nax costs --limit 50
nax costs --jsonShows credits and token usage for recent workflow runs with a grand total. Runs that reported no usage are listed without numbers.
nax dashboard
nax dashboard [workflow]
nax dashboard --run <runId>
nax dashboard --no-open --no-tailDashboard runs stream child workflow output to the terminal by default. Pass
--no-tail to keep the dashboard terminal quiet.
nax mcp
nax mcp
nax mcp setup claude --scope <project|local|user> [--dry-run]
nax mcp doctorThe bare command serves the multi-project NAX control plane over stdio and is
normally launched by an MCP client. --project-root <path> changes only the
default project hint; individual calls can route by project_ref and
scope_id. setup claude previews and writes the portable, path-free Claude
Code entry while preserving unrelated servers. Project scope provides a
reviewable .mcp.json; local scope keeps the entry out of the repository;
user scope creates one entry shared across Claude projects.
doctor is read-only. It checks the executable, package, MCP SDK, Claude
configuration, project identity, private dashboard registry, health and auth,
version, selected Netlify target, capabilities, and context_get. It never
plans or starts a remote run.
nax admin
nax admin sync [target]
nax admin clean blobs
nax admin skills installnax ci
nax ci 'npm test && npm run build'Outside Agent Runner, nax ci exits successfully without running the command. Inside Agent Runner it executes through the shell and exits with the command status.
See also
- Run workflows for task-oriented examples.
- Workflow file reference for
flow.*files. - Configuration reference for environment variables.
- MCP reference for tools, resources, prompts, and safety behavior.