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. An LLM agent explores your codebase and generates a test based on your natural-language description. If no description is provided, you will be prompted for test details interactively.

axm add [description]

Flags:

Examples:

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

# No description: prompts for name, condition, globs, severity, tags
axm add

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       not run         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
• not run - 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>

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

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.3 | node v22.0.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 using a device code flow. Displays a one-time code and opens a browser to authorize. The token is stored locally at ~/.axiomatic/credentials.

axm login

Flags:

After logging in, axm run automatically syncs results and shared agent memory to the dashboard. In CI, set the AXM_TOKEN environment variable instead.

axm install

Install a test pack from the Axiomatic library. Fetches pack definitions from the platform API, adapts them to your codebase using an LLM, and writes YAML test files to the axiomatic/ directory. Existing files with the same name are skipped.

When run without a pack name, Axiomatic scans your project's dependencies and suggests matching packs interactively.

axm install [pack]

Arguments:

Flags:

Examples:

# Scan your project and suggest packs interactively
axm install

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

# Install without LLM adaptation (use templates as-is)
axm install owasp-security --no-adapt

The command fetches pack metadata from the platform API, uses an LLM to adapt the test conditions and file globs to your specific codebase, 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.

axm status

Show authentication and sync status. Checks whether you are logged in, verifies your token is valid, and confirms the current repository is configured for sync.

axm status

Example output:

  Axiomatic - status

  ✓ Authenticated via ~/.axiomatic/credentials
  ✓ User: kevz · kev@example.com
  ✓ Repo: kevz/my-project
  ✓ Sync: results will upload after each run