Structum CLI Reference

The structum command-line interface provides development and maintenance tools for Structum projects.

Overview

The Structum CLI is built with Typer and provides an industry-grade developer experience with rich console output, progress indicators, and comprehensive help text.

Installation

The CLI is included in the meta package:

# From source (current - Alpha)
git clone https://github.com/PythonWoods/structum.git
cd structum
uv sync --extra dev

# Future: From PyPI
pip install structum

Usage

# Show all commands
structum --help

# Show help for specific command
structum check --help

# Show help for subcommand group
structum license --help

Commands

check

Run code quality checks including Ruff linting and Black formatting.

Options:

  • --ruff-only - Skip Black check, run only Ruff

  • --black-only - Skip Ruff check, run only Black

Examples:

# Run all checks
structum check

# Run only linting
structum check --ruff-only

# Run only formatting
structum check --black-only

build-docs

Build Sphinx documentation with configurable options.

Options:

  • --clean - Remove _build directory before building

  • --strict - Treat warnings as errors (recommended for CI)

Examples:

# Standard build
structum build-docs

# Clean build with strict checking
structum build-docs --clean --strict

License Management

The license subcommand group provides REUSE compliance and SPDX header management.

license check

Verify REUSE compliance - ensure all files have proper licensing.

Example:

# Verify all files are compliant
structum license check

license add-header

Add standard SPDX header to a source file with automatic copyright detection.

Options:

  • --force / -f - Overwrite existing header if present

  • --auto - Automatically detect author from git config (user.name and user.email)

  • --author NAME - Manual author name (requires --email)

  • --email EMAIL - Manual author email (requires --author)

Default Behavior:

Without options, uses PythonWoods Team as copyright holder (for core team members).

Automatic Detection (recommended for contributors):

Reads author information from git configuration:

# Configure git (if not already done)
git config user.name "Your Name"
git config user.email "your@email.com"

# Add header with auto-detection
structum license add-header --auto src/mymodule.py

# Generates:
# SPDX-FileCopyrightText: 2026 Your Name <your@email.com>
# SPDX-License-Identifier: Apache-2.0

Manual Specification:

Override git config or specify different author:

structum license add-header src/mymodule.py \
    --author "Mario Rossi" \
    --email "mario@example.com"

Common Workflows:

# Core team: Default copyright
structum license add-header src/core/new_feature.py

# External contributor: Auto-detect from git
structum license add-header --auto src/plugins/contrib.py

# Update outdated header
structum license add-header --force --auto src/old_file.py

Validation Rules:

  • Cannot use --auto with --author or --email (conflict)

  • If using manual specification, both --author AND --email are required

  • Only Python files (.py) are currently supported

Error Handling:

If git config is not set or incomplete when using --auto, falls back to default PythonWoods Team.

license deps-check

Audit all dependencies for license compatibility with Apache-2.0.

Example:

# Scan all dependencies
structum license deps-check

Exit Codes

All commands return standard exit codes:

  • 0 - Success

  • 1 - Failure (checks failed, build errors, non-compliance, etc.)

Integration with CI/CD

Example GitHub Actions workflow:

name: Quality Checks

on: [push, pull_request]

jobs:
  checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install uv
          uv sync --extra dev

      - name: Run quality checks
        run: uv run structum check

      - name: Verify license compliance
        run: uv run structum license check

      - name: Build documentation
        run: uv run structum build-docs --strict

See Also