Skip to Content
ReferenceCommands

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]
FlagPurpose
--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.
--createCreate a Netlify project when none is linked.
--dryPreview setup without writing files or secrets.
--github-actionsEnable GitHub Actions transport setup.

nax run

nax run [flow] [OPTIONS]
nax run agent <claude|codex|gemini|opencode> [prompt...] [OPTIONS]
FlagPurpose
--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.
--dryPreview without creating issues, jobs, or artifacts.
--forceSkip confirmation prompts.
--retry [run-id]Retry one failed Netlify API agent run and continue.
--resume <run-id>Resume a saved Netlify API run in place: keep finished agents, resubmit only unfinished ones. With --dry, only preview; with --force, skip confirmation and allow a moved branch or ambiguous resubmission. See Resume runs.
--include-cancelledWith --resume, also resubmit cancelled agents.
--force-unlockWith --resume, take over a run lock whose owner process is gone.

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:high

Bare 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]
FlagPurpose
--workflow <id>Workflow artifact id.
--runner <id>Agent runner id.
--session <id>Agent session id.
-c, --copyCopy selected summary to the clipboard and exit.
--openOpen 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.
--findingsPrint the structured findings for the run (add --json for the findings.json artifact).
--to <target>Send selected findings to github-issues, pr-review, or beads.
--select <ids> / --limit <n>With --to, choose exact finding ids or the top N ranked findings.
--min-severity <level>With --to, lowest severity offered (default low).
--include-contested / --include-rejectedWith --to, widen the candidate findings.
--label <name>With --to github-issues, extra issue label; repeatable.
--repo <owner/name> / --pr <number>With --to github-issues or pr-review, target repository and pull request.
--dryWith --to, print the plan without creating anything.
--forceSkip confirmation; required to apply --to without a terminal. With pr-review, also posts another review for a run that already has one.

See Hand off findings.

nax list

nax list --verbose
nax list --json

nax lint

nax lint
nax lint review
nax lint --json
nax lint --strict

Checks every discovered flow, or only the named ones, and prints each diagnostic with a fix. Exits 1 when any flow is invalid; with --strict, warnings also fail. See Validate your flow.

nax costs

nax costs
nax costs --limit 50
nax costs --json

Shows 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-tail

Dashboard 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 doctor

The 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 install

nax 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

Last updated on
Agent Runner SDKMCP