CLI Commands

Relevant source files

• src/afterpython/cli/commands/build.py
• src/afterpython/cli/commands/init.py
• src/afterpython/cli/commands/sync.py
• src/afterpython/tools/pyproject.py

The afterpython CLI provides a unified interface to all project management tasks through the ap command. The system includes over 20 commands organized into six functional categories, implemented using the Click framework with optional Trogon TUI support.

CLI Entry Points

The afterpython CLI is accessible through two entry points defined in pyproject.toml:

Entry Point	Purpose	Module
ap	Main CLI with all commands	afterpython.cli.main:afterpython_group
pcu	Python dependency checker/updater	afterpython.utils:pcu_command

The ap command serves as the primary interface, implementing an auto-sync mechanism that runs ap sync before most commands when AP_AUTO_SYNC=1. This ensures configuration files remain synchronized across pyproject.toml, afterpython.toml, authors.yml, and myst.yml files.

Command Structure Diagram

Sources: src/afterpython/cli/main.py28-45

Command Categories

The CLI commands are organized into six functional categories, each serving a distinct role in the project lifecycle:

Project Lifecycle Commands

Commands for initializing, synchronizing, and building projects. These form the core workflow from project setup to deployment.

Command	Function	Module
ap init	Initialize project structure, configs, workflows	src/afterpython/cli/commands/init.py
ap sync	Synchronize configuration files	src/afterpython/cli/commands/sync.py
ap build	Build MyST content and SvelteKit website	src/afterpython/cli/commands/build.py
ap dev	Start development server	src/afterpython/cli/commands/dev.py
ap preview	Preview production build locally	src/afterpython/cli/commands/preview.py

See Project Lifecycle Commands (4.2) for detailed documentation.

Content Management Commands

Commands for managing and serving the five content types supported by MyST: documentation, blog posts, tutorials, examples, and guides.

Command	Content Type	Implementation
ap start	Start all content servers	src/afterpython/cli/commands/start.py
ap doc	Start doc server	src/afterpython/cli/commands/start.py
ap blog	Start blog server	src/afterpython/cli/commands/start.py
ap tutorial	Start tutorial server	src/afterpython/cli/commands/start.py
ap example	Start example server	src/afterpython/cli/commands/start.py
ap guide	Start guide server	src/afterpython/cli/commands/start.py

See Content Management Commands (4.3) for detailed documentation.

Dependency Management Commands

Commands for managing Python and system dependencies through uv and pixi, plus Node.js dependencies through pnpm.

Command	Function	Underlying Tools
ap install	Install all dependencies	uv sync, pixi install
ap add <pkg>	Add dependency	uv add, pixi add
ap remove <pkg>	Remove dependency	uv remove, pixi remove
ap lock	Lock dependencies	uv lock, pixi lock
ap update deps	Update minimum versions	pcu utility
ap update website	Update website template	git clone + copy
ap clean	Clean build artifacts	Directory removal

See Dependency Management Commands (4.4) for detailed documentation.

Code Quality Commands

Commands for enforcing code quality standards through ruff and pre-commit.

Command	Aliases	Function
ap check	ap lint	Run ruff check
ap format	-	Run ruff format
ap pre-commit	ap pc, ap precommit	Run pre-commit hooks

See Code Quality Commands (4.5) for detailed documentation.

Version Control and Release Commands

Commands for managing commits, versions, and releases using commitizen and GitHub workflows.

Command	Aliases	Function
ap commit	-	Run pre-commit + commitizen commit
ap cz	ap commitizen	Direct commitizen access
ap bump	-	Bump version with commitizen
ap release	-	Push release tag to trigger workflow
ap init-branch-rules	-	Create GitHub branch protection rules

See Version Control and Release Commands (4.6) for detailed documentation.

Sources: src/afterpython/cli/commands/init.py src/afterpython/cli/commands/sync.py src/afterpython/cli/commands/build.py afterpython/doc/package_maintenance/package_management.md afterpython/doc/package_maintenance/package_releases.md afterpython/doc/package_maintenance/commit_workflow.md

Command Implementation Pattern

All commands follow a consistent implementation pattern using Click decorators and the context object:

Standard Command Pattern

Commands access project paths through ctx.obj['paths'], which provides attributes like afterpython_path, website_path, build_path, and static_path. Many commands wrap external tools (like ruff, myst, pnpm) via subprocess.run().

Sources: src/afterpython/cli/commands/init.py42-108 src/afterpython/cli/commands/build.py145-233

Configuration Synchronization System

The CLI implements an automatic configuration synchronization mechanism to maintain consistency across multiple configuration files.

Configuration Sync Flow

The sync command propagates metadata changes from source files to derived configurations. When AP_AUTO_SYNC=1, this runs automatically before most commands to ensure all configurations are up-to-date.

Auto-sync Implementation

The auto-sync mechanism is implemented in afterpython_group at src/afterpython/cli/main.py38-45 It:

1. Checks if AP_AUTO_SYNC environment variable equals "1"
2. Skips sync if the invoked command is sync or init (prevents recursion)
3. Runs subprocess.run(["ap", "sync"]) before executing the actual command

Sources: src/afterpython/cli/commands/sync.py1-126 src/afterpython/cli/main.py38-45

Build System Integration

The build command orchestrates a multi-phase build process that transforms content and configuration into a deployable website.

Build Pipeline Phases

The build system handles BASE_PATH determination at src/afterpython/cli/commands/build.py27-60 by checking if the website URL contains "github.io" (GitHub Pages subdirectory deployment) or uses a custom domain (root deployment).

Sources: src/afterpython/cli/commands/build.py62-233

Initialization System

The init command bootstraps a new afterpython project by creating directory structures, configuration files, and GitHub workflows.

Initialization Sequence

The initialization process includes several prompts (controlled by --yes flag) for optional configurations. Each initialization function checks for existing files to prevent overwriting.

Key Initialization Functions:

• init_pyproject() at src/afterpython/tools/pyproject.py66-111: Adds build-system section and project URLs
• init_ruff_toml() at src/afterpython/cli/commands/init.py9-16: Copies ruff template configuration
• init_website() at src/afterpython/cli/commands/init.py19-21: Clones project website template

Sources: src/afterpython/cli/commands/init.py42-108 src/afterpython/tools/pyproject.py66-111

Environment Variable Usage

The CLI respects several environment variables that control behavior:

Variable	Values	Effect
AP_AUTO_SYNC	"0" or "1"	Enable/disable automatic configuration sync before commands
AP_MOLAB_BADGE	"0" or "1"	Enable/disable Molab badge insertion during builds
BASE_PATH	URL path	Override base path for website builds

Environment variables are loaded from .env files using python-dotenv during CLI initialization.

Sources: afterpython/cli/main.py34 afterpython/cli/main.py38-45

Quick Reference

For a complete command reference table with syntax and examples, see Command Reference Table.

For detailed documentation of each command category:

• Project Lifecycle Commands - init, sync, build, dev, preview
• Content Management Commands - start, doc, blog, tutorial, example, guide
• Maintenance Commands - update, install, clean
• Code Quality Commands - check, format, pre-commit
• Version Control Commands - commit, bump, commitizen, release