CLI reference

Axx runs acceptance criteria that people can read, written as Gherkin scenarios, as black-box tests against locally built services: REST + OpenAPI, WireMock, SQL, MongoDB and Kafka out of the box, extended with packs of your own steps.

Axx (github.com/nimbusxr/axx, “axxeptance”) is a human-readable acceptance testing framework for the agentic era.

Command	Purpose
axx run	Start the apps, 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 apps from axx.yaml and keep them running between axx runs
axx down	Stop apps 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 and AGENTS.md
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 fixtures	Generate, check and adopt schema-governed fixture files (the fixture factory)
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 pack	Manage the packs this project uses (axx-packs.yaml)

Usage:
  axx [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  docs        Generate reference documentation from the installed version
  doctor      Check that this project and machine are ready to run axx
  down        Stop apps started by `axx up` (and any left behind by an interrupted run)
  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
  ide         Generate IDE run/debug configurations from axx.yaml
  init        Set up axx in this project: axx.yaml, its packs, a smoke feature, CI and AGENTS.md
  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)
  pack        Manage the packs this project uses (axx-packs.yaml)
  run         Start the apps, 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 apps 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)

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.