Skip to content

Developer CLI Guide

Blueprints includes a command-line interface for development automation, designed to simplify developing and contributing to the project.

Requirements

The CLI requires uv to be installed. If not present, you'll see a warning message with installation instructions.

Install uv: 

pip install uv
# or visit https://github.com/astral-sh/uv

Installation

Install the CLI with its dependencies:

uv sync --group cli
Help

Use blueprints --help or bp --help to see available commands and options.

blueprints --help              # Show general help
blueprints <command> --help    # Show command-specific help

                                                                                
 Usage: blueprints [OPTIONS] COMMAND [ARGS]...                                  
                                                                                
 Blueprints - Development automation CLI                                        

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --version  -v        Show the CLI version.                                   │
│ --help               Show this message and exit.                             │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ install     Sync all dependencies and create venv if needed.                 │
│ lint        Lint with Ruff.                                                  │
│ formatting  Format code using Ruff's formatter.                              │
│ typecheck   Run static type checks with ty from astral.                      │
│ test        Run tests with pytest.                                           │
│ coverage    Run tests and generate coverage reports.                         │
│ check       Run all quality checks before making a PR.                       │
│ docs        Serve documentation locally with live reload.                    │
╰──────────────────────────────────────────────────────────────────────────────╯

Alias

All commands can be invoked using the bp alias as well.

Available Commands

Environment Setup

blueprints install

  • Sync all dependencies (creates venv automatically if needed)

Quality Assurance

blueprints check (Recommended before PR)

  • Run all quality checks in sequence: lint, format, typecheck, coverage
  • Provides detailed summary of which checks passed/failed
  • Exits with code 0 on success, 1 on any failure (CI-friendly)
  • Continues all checks even if one fails (full visibility)
Pre-PR Workflow :rocket:

Before submitting a pull request, run:

blueprints check

This single command validates all aspects of your changes:

  1. Linting - Code style and quality checks with Ruff
  2. Formatting - Code formatting compliance with Ruff
  3. Type Checking - Static type validation with ty
  4. Coverage - Code coverage validation and HTML report generation

Success Output:

============================================================
Running comprehensive quality checks...
============================================================

1. Linting with Ruff...
Lint: PASSED

2. Checking formatting with Ruff...
Format: PASSED

3. Running type checks with ty...
Type Check: PASSED

4. Checking code coverage...
Coverage: PASSED
HTML report generated in htmlcov/

============================================================
Quality Check Summary
============================================================
Passed (4): Lint, Format, Type Check, Coverage
All checks passed! Ready for PR.

Failure Output:

If any check fails, the command will show which ones failed and exit with code 1:

============================================================
Quality Check Summary
============================================================
Passed (3): Lint, Format, Type Check
Failed (1): Coverage

Code Quality

blueprints lint

  • Run Ruff linter for code style and quality checks

blueprints formatting

  • Format code in place using Ruff (modifies files by default)
  • To only check formatting compliance without making changes, add --check: blueprints formatting --check

blueprints typecheck

  • Run ty static type checker on blueprints package

Testing

blueprints test

  • Run all tests in parallel using pytest with xdist
  • Use --light flag to skip slow tests for rapid iteration

blueprints coverage

  • Run tests with coverage reporting and enforce 100% coverage by default
  • Generate terminal report with missing coverage details
  • Use --xml to also generate XML coverage report for CI/CD integration
  • Use --html to also generate interactive HTML coverage report in htmlcov/
  • Use --no-enforce to generate reports without enforcing 100% coverage

Documentation

blueprints docs

  • Serve documentation locally with live reload (initial build may take 5+ minutes)
  • Opens documentation server at http://localhost:8000
  • Browser automatically refreshes when docs are updated
  • Perfect for working on documentation
  • Press Ctrl+C to stop the server

Pass-Through Arguments

All CLI commands support passing additional arguments to the underlying tools. This allows you to access tool-specific options without waiting for CLI updates.

Install with Flags

blueprints install --upgrade            # Upgrade all packages to latest versions
blueprints install --python 3.13        # Use specific Python version

Test with pytest Flags

blueprints test -k test_specific        # Run tests matching pattern
blueprints test --verbose --pdb         # Verbose output with debugger
blueprints test -x                      # Stop on first failure
blueprints test --light -k test_fast    # Fast tests with pattern filter
blueprints test --light                 # Skip slow tests for rapid iteration

Lint with Ruff Flags

blueprints lint --fix                   # Auto-fix detected issues
blueprints lint --select E501           # Check specific rules
blueprints lint --show-fixes            # Show suggested fixes

Format with Ruff Flags

blueprints formatting --line-length 100     # Use specific line length

Type Checking with ty Flags

blueprints typecheck --verbose           # Enable verbose mode
blueprints typecheck --quiet             # Suppress output

Coverage with Options and pytest Flags

blueprints coverage                     # Terminal report with 100% enforcement
blueprints coverage --xml               # Also generate XML report
blueprints coverage --html              # Also generate HTML report
blueprints coverage --xml --html        # Generate all three formats
blueprints coverage --no-enforce        # Skip 100% coverage enforcement
blueprints coverage -k test_pattern     # Filter tests by pattern

Version Information

Check the CLI version:

blueprints --version
# or
blueprints -v

Troubleshooting

Install uv: 

pip install uv

Install with CLI group: 

# With pip
pip install blue-prints[cli]

# With uv
uv sync --group cli

The test group is not installed. Reinstall: 

uv sync --group test