Skip to content

Getting Started

This tutorial walks you through installing axm-audit and running your first project audit.

Prerequisites

  • Python 3.12+
  • uv (recommended) or pip

Installation

Bash
uv add axm-audit

Or with pip:

Bash
pip install axm-audit

Step 1: Run an Audit

CLI

Bash
uv run axm audit . --json-output

Python API

Python
from pathlib import Path
from axm_audit import audit_project

result = audit_project(Path("."))
print("Grade:", result.grade, "Score:", result.quality_score)

The AuditResult contains every check result, a composite score, and a letter grade.

Step 2: Inspect Results

Python
print(f"Passed: {result.total - result.failed}/{result.total}")

for check in result.checks:
    icon = "✅" if check.passed else "❌"
    print(f"{icon} {check.rule_id}: {check.message}")

    if not check.passed and check.fix_hint:
        print(f"   💡 {check.fix_hint}")

Step 3: Filter by Category

Focus on a specific area:

Bash
# CLI
axm audit . --json-output --category lint
axm audit . --json-output --category security
Python
# Python API
result = audit_project(Path("."), category="lint")

# Quick mode (lint + type only, fastest)
result = audit_project(Path("."), quick=True)

Available categories

lint, type, complexity, security, deps, testing, test_quality, architecture, practices, structure, tooling

Step 4: Get JSON Output

Use the Python API when you need the complete JSON-serializable payload:

Python
from axm_audit.formatters import format_json
import json

print(json.dumps(format_json(result), indent=2))

Next Steps

A fresh uv add environment exposes executables through uv run. Prepare the target's mypy/stubs before type audits. Full audits can run project tests and invoke dependency scanners; start with a category when learning the tool. Node projects use different tooling.

A zero command exit means execution succeeded, not all checks passed. Inspect JSON failed; for CI use the explicit verdict gate.