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

uv add axm-audit

Or with pip:

pip install axm-audit

Step 1: Run an Audit

CLI

axm-audit audit .

# Or via the unified AXM CLI
axm audit .

Python API

from pathlib import Path
from axm_audit import audit_project

result = audit_project(Path("."))
print(f"Grade: {result.grade} — {result.quality_score:.1f}/100")

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

Step 2: Inspect Results

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:

# CLI
axm-audit audit . --category lint
axm-audit audit . --category security

# 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, architecture, practices, structure, tooling

Step 4: Get JSON Output

axm-audit audit . --json

from axm_audit.formatters import format_json
import json

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

Next Steps