relm

The Monorepo Manager for Python. "Batteries Included" CLI for managing your Python mono-repo or multi-project workspace. Automate versioning, git tagging, PyPI releases, and local environment setup with a single tool.

⚡ Quick Start (The "5-Minute Rule")

Prerequisites

• Python 3.8+
• Docker (Optional, for containerized workflows)
• Git (Required for version control operations)

Installation

Install globally with pipx (recommended) or pip:

# Recommended
pipx install relm

# Alternative
pip install relm

Run

Start managing your workspace instantly:

# Discover projects in the current directory
relm list

Demo

Copy-paste this snippet to see relm in action (assumes you have a Python project structure):

# 1. List all projects and their current versions
relm list

# 2. Check git status across the entire workspace recursively
relm status all -r

# 3. Install all projects in editable mode in parallel
relm install all -p

# 4. Run tests in parallel across all projects in the 'packages' folder
relm pytest packages -p --from-root

# 5. Release a patch version for a specific library
relm release my-library patch

✨ Features (The "Why")

Core

• Automated Discovery: Recursively scans and identifies Python projects (pyproject.toml) in your workspace with configurable depth.
• Smart Versioning: Semantically bumps versions (major, minor, patch, alpha, beta, rc) and updates files automatically.
• Zero-Config Git Ops: Auto-stages, commits, tags, and pushes releases with standardized messages.

Performance & Workflow

• High-Performance Parallelism: Execute pytest, install, or run commands concurrently across projects while respecting the dependency graph.
• Path-Based Targeting: Target operations at specific folders (e.g., relm pytest packages) or the entire workspace.
• Dependency Awareness: Topologically sorts projects to ensure correct build order, with lenient handling for circular dependencies.
• "From Root" Execution: Seamlessly run commands from the workspace root to avoid monorepo import issues.
• Workspace Cleaning: Instantly wipe dist/, build/, and __pycache__ artifacts with relm clean.

Automation & Security

• Automated Changelog: Parses Conventional Commits to auto-generate CHANGELOG.md.
• PyPI Publishing: seamless build and upload workflow.
• Memory-Safe Logging: Captures only the "tail" of logs during parallel execution to prevent terminal crashes on massive monorepos.
• Safety Checks: Prevents accidental execution in system roots.

🛠️ Configuration (The "How")

relm is configured via a .relm.toml file in your workspace root and CLI arguments.

Environment Variables

relm primarily uses .relm.toml for configuration, but respects standard tool variables:

CLI Arguments

Global Options

Commands

🏗️ Architecture

relm uses a modular architecture designed for maintainability and separation of concerns.

Directory Tree

src/relm/
├── commands/           # 🔌 Pluggable Command Modules
│   ├── pytest_command.py
│   ├── release_command.py
│   └── ...
├── core.py             # 🧠 Project Model & Dependency Graph
├── runner.py           # ⚡ Parallel Task Execution Engine
├── config.py           # ⚙️ Configuration Loader (.relm.toml)
├── git_ops.py          # 🐙 Git Wrapper
├── release.py          # 🚀 Release Workflow Engine
├── versioning.py       # 🏷️ SemVer Logic
├── changelog.py        # 📝 Changelog Generator
├── main.py             # 🏁 CLI Entry Point
└── banner.py           # 🎨 ASCII Art

Data Flow

1. Discovery: main.py bootstraps and calls core.py to recursively find pyproject.toml files.
2. Graph Construction: Projects are parsed into Project objects; dependencies are mapped.
3. Topological Sort: Projects are ordered so dependencies are processed first (with cycle-breaking logic).
4. Execution: The runner.py engine orchestrates execution (sequential or parallel), capturing truncated logs for safety.

🐞 Troubleshooting

Common Issues

Debug Mode

relm uses rich for output. Exceptions are printed with tracebacks on failure. In parallel mode, full output is only shown for failed projects (truncated to the last 50 lines).

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

🗺️ Roadmap

See ROADMAP.md for the full vision.

• Bulk Release Support
• Task Runner (relm run)
• Project Status (relm status)
• Pre-release Version Support (alpha, beta, rc)
• Automated Changelog Generation
• Configuration File Support (.relm.toml)
• Dependency Graph Awareness
• Parallel execution for run, install, and pytest
• Recursive project discovery
• Interactive mode for project selection
• Docker container support
• CI/CD Integration templates