CLI reference

Axx runs executable acceptance criteria, in Gherkin people can read, as black-box tests against running services and apps. Its packs cover REST and OpenAPI, WireMock, SQL, MongoDB, Kafka, logs, files, web apps in real browsers, and AWS, Google Cloud and Azure services: a project lists those it uses in axx-packs.yaml, beside packs of its own steps.

Writing tests: axx steps every step of the project’s packs, one line each axx steps show <id> one step’s documentation and examples axx up start the services once and keep them running axx run –compact run the features; also reports what validate and lint find (axx validate checks the features without running them)

Docs: https://axx.nimbusxr.us (every page as Markdown: add .md to its path; llms.txt lists them)

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.

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
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 between axx runs
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 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)

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
  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 between `axx run`s
  validate    Check feature files without running them: syntax, undefined and ambiguous steps
  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.