CLI Reference

Global Options

These flags can be passed to any command:

axm init

Initialize Axiomatic in your project. Creates an axiomatic.yml config file at the repo root and an axiomatic/ directory with starter tests. By default, an LLM agent explores your codebase and generates 3--5 relevant tests automatically.

axm init

Flags:

If axiomatic.yml or axiomatic/ already exists, you will be prompted to confirm before overwriting.

axm run

Run all tests (or a filtered subset) and report results.

axm run [options]

Flags:

Exit Codes:

Examples:

# Run all tests
axm run

# Run only security-tagged tests with verbose output
axm run --tag security --verbose

# Run with a specific model, bypassing cache
axm run --model claude-sonnet-4-6 --no-cache

# Run tests matching a glob pattern
axm run --filter "**/auth*"

# Preview what would run and estimated cost
axm run --dry-run

# CI-friendly: stop on first failure, quiet output
axm run --bail --quiet

# Output JSON for programmatic consumption
axm run --json

# GitHub Actions annotation format
axm run --format github

# Retry flaky tests up to 2 times
axm run --retries 2

axm add

Add a new invariant test. By default, an LLM agent explores your codebase and generates a test based on your natural-language description. Falls back to interactive prompts if no description is provided or if --interactive is passed.

axm add [description]

Flags:

Examples:

# LLM-driven: describe what you want to test
axm add "all API routes require authentication"

# Interactive mode: prompts for name, condition, globs, severity, tags
axm add --interactive
axm add            # also falls back to interactive when no description given

axm list

List all discovered tests along with their severity, cache status, and tags. Useful for getting an overview of your test suite.

axm list
axm ls        # alias

Example output:

  Axiomatic -- list

  TEST                  SEVERITY    STATUS          TAGS
  ────────────────────  ──────────  ──────────────  ────────────────────
  auth-required         error       pass            security, api
  no-console-log        warning     stale           code-quality
  no-secrets            error       pending         security

  3 test(s) total

Cache status values:

• pass -- cached result, test passed
• fail -- cached result, test failed
• stale -- cached result exists but files have changed since last run
• pending -- no cached result, test has not been run yet

axm show

Show cached results, violations, and agent reasoning for a specific test. Useful for understanding why a test passed or failed without re-running it.

axm show <test> [options]

The <test> argument can be a short name (e.g., no-secrets) or a full path (e.g., axiomatic/no-secrets.yml).

Flags:

Example:

axm show no-secrets

  Test:       axiomatic/no-secrets.yml
  Condition:  No source files should contain hardcoded secrets...
  Status:     PASS
  Confidence: 95%
  Cost:       $0.0042
  Last run:   2025-01-15T10:30:00Z

  Notes:
    Scanned 47 files in src/. No hardcoded secrets found.
    All sensitive values reference process.env.

  Referenced files:
    src/config/database.ts
    src/lib/auth.ts

axm validate

Lint and validate all axiomatic/**/*.yml test files without running them. Checks for YAML syntax errors, missing required fields, invalid severity levels, and other common issues.

axm validate

Example output:

  Axiomatic -- validate

  PASS  axiomatic/auth-required.yml
  PASS  axiomatic/no-console-log.yml
  FAIL  axiomatic/broken-test.yml
        error  axiomatic/broken-test.yml:3  'condition' is required and must be a non-empty string

  3 file(s) validated: 1 error(s)

Checks performed:

• Valid YAML syntax
• condition field is present and non-empty (warns if under 20 characters)
• on field contains valid relative glob patterns (no absolute paths, no ../ traversal)
• severity is one of error, warning, or info
• tags is an array of strings
• provider is one of anthropic or openai

axm doctor

Check your Axiomatic setup for common issues. Validates that axiomatic.yml exists, the axiomatic/ directory is present, an API key is available, and test files are found.

axm doctor

Example output:

  Axiomatic -- doctor

  PASS  axiomatic.yml
        provider: anthropic, model: claude-sonnet-4-6
  PASS  axiomatic/ directory
        /path/to/project/axiomatic
  PASS  API key (anthropic)
        ANTHROPIC_API_KEY set (sk-ant-...xxxx)
  PASS  Test files
        4 test file(s) found
  PASS  Versions
        axm 0.0.1 | node v20.10.0 | darwin arm64

  All checks passed. You're good to go!

axm watch

Run tests in watch mode. Axiomatic monitors your source files and re-runs affected tests when files change.

axm watch [options]

Flags:

The watcher uses the on glob in each test to determine which file changes trigger which tests. Only affected tests re-run.

axm login

Authenticate with the Axiomatic platform. Opens a browser for OAuth authentication and stores the token locally at ~/.axiomatic/credentials.

axm login

Flags:

After logging in, you can sync results to the dashboard for history and team visibility.

axm sync

Push test results to the Axiomatic platform. Reads cached results from .axiomatic/cache.db and uploads them. Requires prior authentication via axm login.

axm sync [options]

Flags:

axm install

Install a test pack from the Axiomatic library. Fetches pack definitions from the platform API and writes YAML test files to the axiomatic/ directory. Existing files with the same name are skipped.

axm install <pack>

Arguments:

Flags:

Examples:

# Install the OWASP security test pack
axm install owasp-security

# Install into a specific project directory
axm install owasp-security --dir ./my-project

The command fetches the pack metadata and test definitions from the platform API (GET /api/library/:packName), then writes each test as a YAML file under axiomatic/. If a file already exists, it is skipped to avoid overwriting local changes.

axm credits

Check your Axiomatic cloud LLM credit balance, usage, and reset date. Requires authentication via axm login.

axm credits

Flags:

Example output:

  Axiomatic — credits

  Plan:        free
  Balance:     $4.82 / $5.00 (96% remaining)
  Used:        $0.18
  Resets:      4/14/2026

Credits are included with your Axiomatic plan and provide access to Claude API without needing your own API key. See Billing for tier details.