axm-init 0.14.0

AXM Init — Python project scaffolding CLI with Copier templates.

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 "[e-mail]"

# 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).

Option	Short	Default	Description
PATH		.	Directory to initialize
--org	-o	required	GitHub org or username
--author	-a	required	Author name
--email	-e	required	Author email
--name	-n	dir name	Project name
--license	-l	Apache-2.0	License (MIT, Apache-2.0, EUPL-1.2)
--license-holder		--org	License holder
--description	-d		One-line description
--workspace	-w	False	Scaffold a UV workspace instead of a standalone package
--member	-m		Scaffold a member sub-package with this name
--check-pypi		False	Verify PyPI availability first
--json		False	Output as JSON

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

axm-init check

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

Option	Short	Default	Description
PATH		.	Directory to check
--category	-c	all	Filter to one category
--verbose	-v	False	Show all checks including passed
--json		False	Output as JSON
--agent		False	Compact agent-friendly output

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

axm-init reserve

Reserve a package name on PyPI with a minimal placeholder.

Option	Short	Default	Description
NAME		required	Package name to reserve
--author	-a	git config	Author name (required)
--email	-e	git config	Author email (required)
--dry-run		False	Skip actual publish
--json		False	Output as JSON

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

Workspace Support

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

Context	Detection	Behavior
STANDALONE	No [tool.uv.workspace]	All checks enabled
WORKSPACE	Has [tool.uv.workspace] at root	CI, tooling, and workspace checks enabled
MEMBER	Is a packages/*/ sub-directory	CI checks excluded (handled at workspace root)

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-mail]

# UV workspace
axm-init scaffold my-workspace --workspace --org myorg --author A --email [e-mail]

# Member sub-package (run from inside workspace)
axm-init scaffold --member my-lib --org myorg --author A --email [e-mail]

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