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
axm-audit audit .

# Or via the unified AXM CLI
axm audit .

Python API

Python
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

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 audit . --category lint
axm-audit audit . --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, architecture, practices, structure, tooling

Step 4: Get JSON Output

Bash
axm-audit audit . --json
Python
from axm_audit.formatters import format_json
import json

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

Next Steps