CLI reference

View .md Open in Claude

Axx (github.com/nimbusxr/axx, “axxeptance”) is an open-source acceptance testing framework, the behavioral verification layer for agentic software factories: it verifies running software against executable acceptance criteria, black-box.

Its criteria are Gherkin scenarios people can read, and its packs give the steps (REST and OpenAPI, WireMock, SQL, MongoDB, Kafka, logs, files, web apps in real browsers, AWS, Google Cloud, Azure): a project lists those it uses in axx-packs.yaml, beside packs of its own steps. All of this answers offline, for this version.

Writing tests: axx steps every step of the project’s packs, one line each: read it once axx steps show <id>… the documentation of steps whose line leaves you unsure, several at once axx validate && axx lint && axx run –compact check the features and the test data, then run, in one command: a run starts the services and stops them axx up, axx down only to keep the services running and inspect them axx explain AXX-E… what an error code means, and what to do

A step the project’s packs lack: axx steps search <words> finds it in Axx’s other packs, with the pack to add; axx pack list says what each pack reaches.

A scenario is one behavior: Given the state it starts from, one When, Then what is true afterwards; a When after a Then is another scenario, and so is each acceptance criterion, even when one action shows several. Every scenario uses data of its own.

Docs for people: https://axx.nimbusxr.us

Command	Purpose
`axx run`	Start the services, run feature files, and report
`axx validate`	Check feature files without running them: syntax, undefined and ambiguous steps, and values that could be read two ways
`axx steps`	List, search and inspect the available Gherkin steps
`axx explain`	Show which step definition a line matches, or what an error code means
`axx up`	Start the services from axx.yaml and keep them running, to inspect them
`axx down`	Stop services started by `axx up` (and any left behind by an interrupted run)
`axx doctor`	Check that this project and machine are ready to run Axx
`axx init`	Set up Axx in this project: axx.yaml, its packs, a smoke feature, CI, AGENTS.md and agents
`axx schema`	Print the JSON Schema for axx.yaml or a fixture spec file
`axx docs`	Generate reference documentation from the installed version
`axx mcp`	Serve Axx to coding agents over the Model Context Protocol (stdio)
`axx skills`	Install agent skills that teach coding agents to use Axx
`axx version`	Print the axx version
`axx completion`	Generate the autocompletion script for the specified shell
`axx config`	The project’s configuration: config show
`axx env`	The services Axx started (running, left over, not cleaned up); env up and env down start and stop them
`axx fixtures`	Generate, check and adopt schema-governed fixture files (the fixture factory)
`axx host`	Start the services for runs that cannot start them, like an agent’s in a sandbox without Docker
`axx ide`	Generate IDE run/debug configurations from axx.yaml
`axx install`	Download the axx version this project runs on, or the one you name, for later runs
`axx lint`	Check test-data isolation: values that must stay unique across seeds, fixtures and features
`axx lsp`	Serve feature-file editing to editors over the Language Server Protocol (stdio)
`axx models`	Stub embedded models: models whose answers are their mappings
`axx pack`	Manage the packs this project uses (axx-packs.yaml)
`axx upgrade`	Upgrade Axx to its newest release, say what changed, and update the skills

Usage:
  axx [flags]
  axx [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  config      The project's configuration: config show
  docs        Generate reference documentation from the installed version
  doctor      Check that this project and machine are ready to run axx
  down        Stop services started by `axx up` (and any left behind by an interrupted run)
  env         The services axx started (running, left over, not cleaned up); env up and env down start and stop them
  explain     Show which step definition a line matches, or what an error code means
  fixtures    Generate, check and adopt schema-governed fixture files (the fixture factory)
  help        Help about any command
  host        Start the services for runs that cannot start them, like an agent's in a sandbox without Docker
  ide         Generate IDE run/debug configurations from axx.yaml
  init        Set up axx in this project: axx.yaml, its packs, a smoke feature, CI, AGENTS.md and agents
  install     Download the axx version this project runs on, or the one you name, for later runs
  lint        Check test-data isolation: values that must stay unique across seeds, fixtures and features
  lsp         Serve feature-file editing to editors over the Language Server Protocol (stdio)
  mcp         Serve axx to coding agents over the Model Context Protocol (stdio)
  models      Stub embedded models: models whose answers are their mappings
  pack        Manage the packs this project uses (axx-packs.yaml)
  run         Start the services, run feature files, and report
  schema      Print the JSON Schema for axx.yaml or a fixture spec file
  skills      Install agent skills that teach coding agents to use axx
  steps       List, search and inspect the available Gherkin steps
  up          Start the services from axx.yaml and keep them running, to inspect them
  upgrade     Upgrade axx to its newest release, say what changed, and update the skills
  validate    Check feature files without running them: syntax, undefined and ambiguous steps, and values that could be read two ways
  version     Print the axx version

Flags:
      --compact               print only what matters (auto-enabled for coding agents)
  -c, --config string         path to axx.yaml (default: search upward from the working directory)
  -h, --help                  help for axx
      --json                  emit machine-readable JSON (stable envelope)
      --no-color              disable colored output
  -v, --verbose count         increase log verbosity (-v, -vv)
      --version axx version   print the axx version (as axx version)

Use "axx [command] --help" for more information about a command.

Every command accepts --json and prints one JSON envelope. Exit codes are listed in exit codes.