​

Contributing to Lumos CLI

​

Reporting issues

​

Development

​

Prerequisites

• Python 3.10.6 or higher
• uv (recommended) or pip

​

Installation

1. Clone the repository:
   git clone https://github.com/teamlumos/lumos-cli.git
   cd lumos-cli
   
2. Install dependencies with uv:
   uv sync --group dev --group docs
   
3. Set up pre-commit hooks:
   uv run pre-commit install
   

​

Running the CLI Locally

alias lumosdev='uv run python -m lumos'

uv run python -m lumos --help

​

Project Structure

lumos-cli/
├── src/lumos/           # Main source code
│   ├── __init__.py
│   ├── __main__.py          # Entry point for `python -m lumos`
│   ├── cli.py               # Main CLI group and core commands
│   ├── common/              # Shared utilities
│   │   ├── client.py        # API client
│   │   ├── client_helpers.py
│   │   ├── helpers.py       # Authentication helpers
│   │   ├── keyhelpers.py    # Credential storage
│   │   ├── logging.py       # Debug logging
│   │   └── models.py        # Pydantic models
│   ├── list_collections/    # `lumos list` subcommands
│   │   └── cli.py
│   └── request/             # `lumos request` subcommands
│       └── cli.py
├── tests/                   # Test files
├── docs/                    # Sphinx documentation (auto-generated)
├── sample-scripts/          # Example scripts for users
├── pyproject.toml           # Project configuration
├── .releaserc.yaml          # Semantic release configuration
└── .github/workflows/       # CI/CD workflows

​

Development Workflow

​

Creating a Branch

1. Create a feature branch from main:
   git checkout -b feat/your-feature-name
   
2. Follow Angular commit conventions:
   • feat: - New features
   • fix: - Bug fixes
   • docs: - Documentation changes
   • refactor: - Code refactoring
   • test: - Adding or updating tests
   • chore: - Maintenance tasks

​

Adding a New Command

1. Create a new module in the appropriate directory (e.g., src/lumos/your_feature/cli.py)
2. Define your click command:
   from click_extra import command, option
   from lumos.common.helpers import authenticate
   
   @command("your-command", help="Description of your command")
   @option("--flag", is_flag=True, help="Option description")
   @authenticate
   def your_command(flag: bool) -> None:
       """Your command implementation."""
       pass
   
3. Register the command in src/lumos/cli.py:
   def register_subcommands():
       from lumos.your_feature.cli import your_command
       cli.add_command(your_command)
   
4. Add tests in tests/
5. Update documentation in docs/

​

Code Style

​

Running Linters

# Run all checks
uv run ruff check .
uv run ruff format --check .
uv run basedpyright

# Auto-fix issues
uv run ruff check --fix .
uv run ruff format .

​

Style Guidelines

• Maximum line length: 120 characters
• Use double quotes for strings
• Use type hints for all function parameters and return values
• Follow PEP 8 naming conventions

​

Testing

​

Running Tests

uv run pytest

​

Running Tests with Coverage

uv run pytest --cov=lumos --cov-report=html

​

Writing Tests

• Place test files in the tests/ directory
• Name test files with _test.py suffix
• Use descriptive test function names: test_command_does_expected_behavior

​

Documentation

​

Building Documentation Locally

# Install docs dependencies
uv sync --group docs

# Build both HTML and Markdown, copy markdown to docs/
make -C docs docs

# Or build individually:
make -C docs html      # HTML only
make -C docs markdown  # Markdown only

# View the HTML docs
open docs/src/_build/html/index.html

​

Documentation Structure

• docs/src/index.md - Main landing page
• docs/src/installation.md - Installation instructions
• docs/src/examples.md - Usage examples with code samples
• docs/src/reference.md - CLI reference with live examples (via click-extra sphinx)

• docs/src/_build/html/ - HTML documentation (deployed to GitHub Pages via semantic-release)
• docs/*.md - Markdown documentation (copied from build, committed during releases)

​

Using click-extra Sphinx Directives

# Define CLI source (hidden by default)
\`\`\`{click:source}
:hide-results:
from lumos.cli import cli
\`\`\`

# Run CLI command and show output with ANSI colors
\`\`\`{click:run}
invoke(cli, args=["--help"])
\`\`\`

​

Updating Documentation

1. For CLI changes: Update docstrings in the source code. The CLI reference uses click:run directives to execute commands and display their help.
2. For usage examples: Edit docs/examples.md with new code samples.
3. For installation changes: Update docs/installation.md and README.md.

​

Release Process

​

Triggering a Release

1. Go to the GitHub Actions page
2. Select the “Release” workflow
3. Click “Run workflow”
4. Optionally enable “Dry run” to preview the release

​

What Happens During Release

1. Version Analysis: semantic-release analyzes commits to determine the next version
2. Build: Cross-platform binaries are built for Linux, macOS, and Windows
3. Documentation: Documentation is regenerated with the new version
4. Release:
   • CHANGELOG.md is updated
   • pyproject.toml version is bumped
   • Git tag is created
   • GitHub Release is published with binaries
   • Homebrew formula is updated

​

Version Bumping

• feat: → Minor version bump (e.g., 1.0.0 → 1.1.0)
• fix: → Patch version bump (e.g., 1.0.0 → 1.0.1)
• BREAKING CHANGE: in commit body → Major version bump (e.g., 1.0.0 → 2.0.0)

​

Manual Release (Emergency)

# Update version manually
uv version X.Y.Z

# Build artifacts
uv build
uv run pyinstaller src/lumos/__main__.py

# Create and push tag
git tag vX.Y.Z
git push origin vX.Y.Z

​

Getting Help

• Issues: GitHub Issues
• Discussions: GitHub Discussions

​

License