axm-init 0.15.0

axm-init — Python project scaffolding, quality checks & governance CLI

Features

• 🚀 Scaffold — Bootstrap production-grade Python projects, workspaces, and member packages
• 📋 Check — Score any project against the AXM gold standard (49 checks, A–F grade)
• 📦 Reserve — Claim a package name on PyPI before you're ready to publish

Installation

uv add axm-init

Quick Start

# Scaffold a new project
axm init_scaffold my-project \
  --org axm-protocols \
  --author "Your Name" --email "you@example.com"

# Check against AXM standards
axm init_check
# Score: 100/100 — Grade A 🏆

# Reserve a name on PyPI
axm init_reserve my-cool-lib --dry-run

CLI Commands

axm init_scaffold

Scaffold a production-grade Python project (src layout, PEP 621, CI, docs).

Note: --workspace and --member are mutually exclusive.

axm init_check

Score a project against the AXM gold standard (49 checks across 8 categories).

Categories: pyproject, ci, tooling, docs, structure, deps, changelog, workspace

axm init_reserve

Reserve a package name on PyPI with a minimal placeholder.

Note: --author and --email fall back to git config user.name / user.email. If both are empty, axm init_reserve exits with an error.

Workspace Support

axm-init detects three project contexts and adapts checks accordingly:

Per-Package Check Exclusions

Workspace members can exclude inapplicable checks via pyproject.toml. Each entry is a prefix of a canonical check name — the category.function_name_without_check_ form shown in the report (e.g. ci.ci_workflow_exists). A bare category like "ci" excludes the whole category:

[tool.axm-init]
exclude = ["ci.ci_workflow_exists", "tooling.makefile"]

Scaffold Modes

# Standalone package (default)
axm init_scaffold my-project --org myorg --author A --email e@e.com

# UV workspace
axm init_scaffold my-workspace --workspace --org myorg --author A --email e@e.com

# Member sub-package (run from inside workspace)
axm init_scaffold --member my-lib --org myorg --author A --email e@e.com

The --member flag auto-detects the workspace root, creates the package under packages/<name>/, and patches root files (Makefile, mkdocs.yml, pyproject.toml, CI workflows).

CI Check Badge

Projects scaffolded with axm init_scaffold include an automated check badge that updates on every push. The badge shows your score and grade using the AXM logo.

push → axm init_check → badge JSON → gh-pages → shields.io

The badge is already in your README — just push to main and it appears after the first CI run.

Existing projects can add the badge too — copy .github/workflows/axm-quality.yml from a scaffolded project and add the badge markup. See the howto guide for details.

Development

This package is part of the axm-forge workspace.

git clone https://github.com/axm-protocols/axm-forge.git
cd axm-forge
uv sync --all-groups
uv run --package axm-init --directory packages/axm-init pytest -x -q

📖 Full documentation

License

Apache-2.0 — © 2026 axm-protocols