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, tool_node, tool_metadata, ToolMetadata, ToolNodeError): AXMTool/ToolResult (with text for pre-rendered output), HookAction/HookResult, WitnessResult/ValidationFeedback/WitnessRule, and tool_node (adapt any axm.tools tool into a DAG python-node) 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 --version                # print the installed axm version (also -V)
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 from entry-point metadata and dispatches lazily — it imports only the one command you invoke, not every tool at startup.

Package Structure

Text Only
axm/
├── src/axm/
│   ├── cli.py            # Lazy, dispatch-first autodiscovery wrapper
│   ├── hooks/
│   │   └── base.py       # HookAction Protocol + HookResult
│   ├── tools/
│   │   ├── base.py       # AXMTool Protocol + ToolResult + ToolMetadata
│   │   └── node.py       # tool_node adapter + ToolNodeError (AXMTool → DAG node)
│   └── witnesses.py      # WitnessResult + ValidationFeedback + WitnessRule
└── tests/

Learn More