relm 3.0.1

A unified CLI tool to manage versioning, git, and PyPI releases for multiple projects.

relm

The "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

Prerequisites

• Python 3.8+
• pip or pipx

Installation

Install globally with pipx (recommended):

pipx install relm

Or with pip:

pip install relm

Usage Example

Manage your projects from the root of your workspace:

# 1. Discover all projects in the current directory
relm list

# 2. Bulk install all projects in editable mode (Developer Mode)
relm install all

# 3. Check git status across all projects
relm status all

# 4. Run a command across all projects (e.g., tests)
relm run "pytest" all --fail-fast

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

Note: relm works by finding pyproject.toml files. Ensure your projects are standard Python packages.

---

✨ Key Features

• Automated Discovery: recursively finds all valid Python projects in your workspace.
• Smart Versioning: Semantically bumps versions (major, minor, patch, alpha, beta, rc) in pyproject.toml and __init__.py.
• Zero-Config Git Ops: Auto-stages, commits, and tags releases with clean messages.
• PyPI Publishing: Builds wheels/sdist and uploads to PyPI automatically.
• Automated Changelog: Parses Conventional Commits to automatically generate and update CHANGELOG.md.
• Configuration: Supports .relm.toml for global configuration.
• Bulk Operations: Release, Install, or Check Status of ALL projects at once.
• Task Runner: Execute any shell command across your entire suite (relm run "...").
• Dependency Awareness: Automatically topological sorts projects during execution (build lib-a before app-b).
• Workspace Cleaning: Quickly remove build artifacts (dist/, build/, __pycache__) with relm clean.
• PyPI Verification: Verify if the locally released version (tag) is available on PyPI with relm verify.
• "Changed Since" Detection: Only list or act on projects modified since a specific git reference using --since.
• Project Scaffolding: Generate new standard Python projects instantly with relm create.
• Developer Friendly: "Safety checks" prevent running in system roots.

---

⚙️ Configuration & Advanced Usage

relm is controlled entirely via CLI arguments.

Global Arguments

Argument	Default	Description
--path	.	Root directory to scan for projects.

Commands

list

Lists all discovered projects, their versions, and paths.

Argument	Description
--since	List only projects changed since the given git ref (e.g., HEAD~1, main, v1.0).

create

Generates a new standard Python project structure.

Argument	Description
name	Name of the new project.
path	Directory to create the project in (default: current directory).

install

Installs projects into the current environment.

Argument	Description
project_name	Name of the project or all.
--no-editable	Install in standard mode (default is editable -e).

run

Executes a shell command in each project's directory.

Argument	Description
command_string	The shell command to execute (e.g., "ls -la").
project_name	Name of the project or all (default: all).
--fail-fast	Stop execution immediately if a command fails.

status

Shows the Git branch and dirty/clean status for projects.

Argument	Description
project_name	Name of the project or all.

verify

Verifies if the locally released version (tag) is available on PyPI.

Argument	Description
project_name	Name of the project or all.

clean

Recursively removes build artifacts (dist/, build/, __pycache__) from projects.

Argument	Description
project_name	Name of the project or all.

release

Orchestrates the version bump, build, and publish flow.

Argument	Description
project_name	Name of the project or all.
type	Bump type: major, minor, patch, alpha, beta, rc, release.
-y, --yes	Skip confirmation prompts.
-m, --message	Custom commit message template (e.g., 'chore: release {version}').

---

🏗️ Architecture

relm follows a modular design to keep concerns separated:

src/relm/
├── commands/        # Modular Command Implementations
│   ├── base.py      # Abstract base for commands
│   └── ...          # Individual command modules (list, release, etc.)
├── __init__.py      # Package init
├── banner.py        # ASCII art logo
├── changelog.py     # Changelog generation logic
├── config.py        # Configuration loading (.relm.toml)
├── core.py          # Project discovery & parsing logic
├── git_ops.py       # Git commands (status, commit, tag, push)
├── install.py       # pip installation wrappers
├── main.py          # CLI Entry Point & Argument Parsing
├── release.py       # Release orchestration workflow
├── runner.py        # Subprocess execution for 'run' command
├── verify.py        # PyPI availability verification
└── versioning.py    # Semantic version bumping

Logic Flow

1. Discovery: main.py loads configuration and calls core.py to map the directory tree.
2. Dispatch: The argparse subparser routes execution to the specific module in src/relm/commands/.
3. Execution: Command modules orchestrate the logic, calling helpers like runner.py, git_ops.py, or changelog.py to interact with the system.

---

🗺️ Roadmap

See ROADMAP.md for the detailed vision.

• Bulk Release Support
• Task Runner (relm run)
• Project Status (relm status)
• Pre-release Version Support (alpha, beta, rc)
• Custom Commit Messages
• Changelog Generation
• Configuration File Support
• Dependency Graph Awareness

---

🤝 Contributing & License

Contributions are welcome! Please submit a PR or open an issue.

Licensed under MIT. See LICENSE for details.