Skip to content

AXM Logo

axm (CLI)

Unified command-line interface for the AXM ecosystem.

CI axm-audit Coverage PyPI

Features

  • 🔌 Autodiscovery — automatically finds commands from installed AXM packages via entry points
  • 🧩 Modular — install only what you need (axm[init], axm[audit], axm[bib], axm[mcp])
  • 🛠️ Shared interface — re-exports the core contracts from the package root (from axm import AXMTool, ToolResult, HookAction, HookResult, WitnessResult, ValidationFeedback, WitnessRule): AXMTool/ToolResult (with text for pre-rendered output), HookAction/HookResult, and WitnessResult/ValidationFeedback/WitnessRule for ecosystem development
  • 📦 Minimal — only depends on cyclopts, everything else is optional

Installation

Bash
uv add axm              # CLI shell only
uv add axm[init]        # + scaffolding & project checks
uv add axm[audit]       # + code quality audits
uv add axm[bib]         # + bibliography tools
uv add axm[mcp]         # + MCP server (for AI agents)
uv add axm[all]         # everything

Usage

Bash
axm                          # shows available commands
axm init_scaffold my-project # if axm-init is installed
axm init_check .             # check project conformity
axm audit .                  # if axm-audit is installed

How It Works

Each AXM package declares commands via pyproject.toml:

TOML
# axm-init/pyproject.toml
[project.entry-points."axm.commands"]
init_scaffold = "axm_init.cli:scaffold"
init_check    = "axm_init.cli:check"
init_reserve  = "axm_init.cli:reserve"

The axm CLI discovers these at startup and exposes them as subcommands.

Package Structure

Text Only
axm/
├── src/axm/
│   ├── cli.py         # Autodiscovery wrapper (~80 lines)
│   ├── hooks/
│   │   └── base.py    # HookAction Protocol + HookResult
│   ├── tools/
│   │   └── base.py    # AXMTool Protocol + ToolResult
│   └── witnesses.py   # WitnessResult + ValidationFeedback + WitnessRule
└── tests/

Learn More