# CLI reference

> Every Axx command and flag, generated from the help text of the installed binary.

Source: https://axx.nimbusxr.us/next/references/cli/

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

```text
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](https://axx.nimbusxr.us/next/references/json-output/). Exit codes are listed in [exit codes](https://axx.nimbusxr.us/next/references/error-codes/#exit-codes).