Skip to main content
pyrig provides a comprehensive CLI for project initialization, configuration management, and build automation. All commands support verbosity flags for flexible logging output.

Quick Reference

uv run pyrig init           # Full project initialization
uv run pyrig mkroot         # Create/update all config files
uv run pyrig mktests        # Generate test skeletons
uv run pyrig mkinits        # Create missing __init__.py files
uv run pyrig build          # Build artifacts (PyInstaller, etc.)
uv run pyrig protect-repo   # Configure repository protection
uv run pyrig scratch        # Execute the project's .scratch file
uv run pyrig rmpyc          # Remove __pycache__ directories
uv run pyrig version        # Display project version

Global Options

All pyrig commands support verbosity control through global flags:

Verbosity Flags

-v
flag
Debug output with level prefix. Can be stacked for more detail.
uv run pyrig -v mkroot      # DEBUG level with level prefix
uv run pyrig -vv mkroot     # DEBUG level with module names
uv run pyrig -vvv mkroot    # DEBUG level with timestamps
-q
flag
Quiet mode - only show warnings and errors (WARNING level).
uv run pyrig -q init

Logging Levels

FlagLevelFormatUse Case
(none)INFOClean messages onlyDefault, production use
-qWARNINGLevel prefix + messageMinimal output
-vDEBUGLevel prefix + messageBasic debugging
-vvDEBUGLevel + module + messageModule-level debugging
-vvvDEBUGTimestamp + level + module + messageFull diagnostic output

Command Categories

Project Setup

  • init - Complete project initialization from scratch
  • mkroot - Create/update configuration files
  • mkinits - Generate missing __init__.py files

Development

  • mktests - Generate test skeletons
  • scratch - Execute temporary .scratch file
  • rmpyc - Clean up __pycache__ directories

Build & Deployment

Utility Commands

  • version - Display project version

Usage Patterns

First-Time Setup

cd my-project
uv init
uv add pyrig
uv run pyrig init

Updating Configuration

# After modifying ConfigFile subclasses
uv run pyrig mkroot

Development Workflow

# Add new modules
uv run pyrig mkinits    # Create __init__.py files
uv run pyrig mktests    # Generate test skeletons

Building for Distribution

uv run pyrig build
# Artifacts created in dist/ with platform-specific names

Command Discovery

pyrig’s CLI uses dynamic command discovery:
  1. Project-specific commands - Functions in <package>.rig.cli.subcommands
  2. Shared commands - Functions in <package>.rig.cli.shared_subcommands across the dependency chain
  3. Main entry point - main() function from <package>.main
This enables creating custom commands that are automatically registered:
# myproject/rig/cli/subcommands.py
def deploy() -> None:
    """Deploy the application."""
    ...
$ uv run myproject deploy
All commands are idempotent and safe to run multiple times unless explicitly noted otherwise.

Next Steps

init Command

Initialize a complete pyrig project

mkroot Command

Generate configuration files

build Command

Build distributable artifacts

mktests Command

Generate test skeletons

Build docs developers (and LLMs) love