Command-line interface for managing reusable configuration templates for modern Python projects.
📖 New to Rhiza? Check out the Getting Started Guide for a beginner-friendly introduction!
📚 Documentation map — Getting Started (start here) · README (overview & full command reference) · Usage Guide (workflows & examples) · CLI Reference (command cheatsheet)
Rhiza is a CLI tool that helps you maintain consistent configuration across multiple Python projects by using templates stored in a central repository. It allows you to:
- Sync (inject) templates into target repositories
- Keep project configurations synchronized with template repositories
- Preview changes with a validating dry-run before applying them
- Overview
- Installation
- Quick Start
- Commands
- Configuration
- Examples
- Development
- Additional Documentation
For more detailed information, see:
- Getting Started Guide - Beginner-friendly introduction and walkthrough
- CLI Quick Reference - Command syntax and quick examples
- Usage Guide - Practical tutorials and workflows
- Authentication Guide - Configuring credentials for private template repositories (GitHub PATs, SSH keys, GitLab tokens)
- Contributing Guidelines - How to contribute to the project
- Code of Conduct - Community guidelines
pip install rhizaTo update to the latest version:
pip install --upgrade rhizauvx is part of the uv package manager and allows you to run CLI tools directly without installing them:
uvx rhiza --helpWith uvx, you don't need to install rhiza globally. Each time you run uvx rhiza, it will automatically use the latest version available on PyPI. To ensure you're using the latest version, simply run your command - uvx will fetch updates as needed:
# Always uses the latest version
uvx rhiza syncIf you want to use a specific version:
uvx rhiza@0.5.6 --helpgit clone https://github.com/jebel-quant/rhiza-cli.git
cd rhiza-cli
pip install -e .git clone https://github.com/jebel-quant/rhiza-cli.git
cd rhiza-cli
make installrhiza --help-
Create the template configuration:
Create a
.rhiza/template.ymlfile in your project by hand. At a minimum it must specify atemplate-repositoryand one ofinclude,templates, orprofiles:template-repository: jebel-quant/rhiza include: - .github - .editorconfig - .gitignore - .pre-commit-config.yaml - Makefile - pytest.ini
-
Preview what would change (optional):
rhiza sync --strategy diff
This validates your configuration and shows what would change without modifying any files.
-
Sync templates into your project:
rhiza sync
This fetches and copies template files into your project (first run) or applies updates via 3-way merge (subsequent runs).
Sync Rhiza configuration templates into a target repository using diff/merge, preserving local customisations.
Usage:
rhiza sync [OPTIONS] [TARGET]Arguments:
TARGET- Target git repository directory (defaults to current directory)
Options:
--branch, -b TEXT- Rhiza branch to use [default: main]--strategy, -s TEXT- Sync strategy:merge(default) ordiff--target-branch TEXT- Create/checkout a branch in the target repo for changes--help- Show help message and exit
Description:
Keeps your project in sync with the template repository. It first loads and
validates .rhiza/template.yml, raising a clear error if the file is missing,
malformed, or missing required fields (template-repository and one of
include/templates/profiles), then:
- First run (no lock file): copies all template files and writes
.rhiza/template.lock - Subsequent runs: computes diff (base → upstream) and applies it via
git apply -3— local edits are preserved
Use rhiza sync --strategy diff for a validating dry-run that shows what would
change without modifying any files.
.rhiza/template.lock is a YAML file that records the full state of the last sync:
sha: abc123def456789abcdef0123456789abcdef0123
repo: jebel-quant/rhiza
host: github
ref: main
include:
- .github/
- .rhiza/
exclude: []
templates: []
files:
- .github/workflows/ci.yml
- .rhiza/template.yml
- MakefileCommit
.rhiza/template.lockto version control — it is the anchor for incremental 3-way merges.
Examples:
# Sync templates (first time or update with 3-way merge)
rhiza sync
# Preview what would change (dry-run)
rhiza sync --strategy diff
# Sync from a specific branch
rhiza sync --branch develop
# Sync to a dedicated branch
rhiza sync --target-branch update-templatesOutput:
[INFO] Target repository: /path/to/project
[INFO] Rhiza branch: main
[INFO] Sync strategy: merge
[INFO] Cloning jebel-quant/rhiza@main (upstream)
[INFO] Upstream HEAD: abc123def456
[INFO] First sync — copying all template files
[COPY] .github/workflows/ci.yml
[COPY] .editorconfig
[COPY] .gitignore
[COPY] Makefile
✓ Sync complete — 4 file(s) processed
Rhiza uses a .rhiza/template.yml file to define template sources and what to include in your project.
The template.yml file uses YAML format with the following structure:
# Required: GitHub or GitLab repository containing templates (format: owner/repo)
template-repository: jebel-quant/rhiza
# Optional: Git hosting platform (default: github)
template-host: github
# Optional: Branch to use from template repository (default: main)
template-branch: main
# Required: List of paths to include from template repository
include:
- .github
- .editorconfig
- .gitignore
- .pre-commit-config.yaml
- Makefile
- pytest.ini
- ruff.toml
# Optional: List of paths to exclude (filters out from included paths)
exclude:
- .github/workflows/specific-workflow.yml
- .github/CODEOWNERS- Type: String
- Format:
owner/repository - Description: GitHub or GitLab repository containing your configuration templates
- Example:
jebel-quant/rhiza,myorg/python-templates,mygroup/gitlab-templates
- Type: String
- Default:
github - Options:
github,gitlab - Description: Git hosting platform where the template repository is hosted
- Example:
github,gitlab
- Type: String
- Default:
main - Description: Git branch to use when fetching templates
- Example:
main,develop,v2.0
- Type: List of strings
- Description: Paths (files or directories) to copy from the template repository
- Notes:
- Paths are relative to the repository root
- Can include both files and directories
- Directories are recursively copied
- Must contain at least one path
Example:
include:
- .github # Entire directory
- .editorconfig # Single file
- src/config # Subdirectory- Type: List of strings
- Description: Paths to exclude from the included set
- Notes:
- Useful for excluding specific files from broader directory includes
- Paths are relative to the repository root
Example:
exclude:
- .github/workflows/deploy.yml # Exclude specific workflow
- .github/CODEOWNERS # Exclude specific filetemplate-repository: jebel-quant/rhiza
template-branch: main
include:
- .github
- .editorconfig
- .gitignore
- .pre-commit-config.yaml
- CODE_OF_CONDUCT.md
- CONTRIBUTING.md
- Makefile
- pytest.ini
- ruff.toml
exclude:
- .github/workflows/release.yml
- .github/CODEOWNERStemplate-repository: mygroup/python-templates
template-host: gitlab
template-branch: main
include:
- .gitlab-ci.yml
- .editorconfig
- .gitignore
- Makefile
- pytest.ini
exclude:
- .gitlab-ci.yml# Create a new project directory
mkdir my-python-project
cd my-python-project
# Initialize git
git init
# Create .rhiza/template.yml by hand (see the Configuration section)
mkdir -p .rhiza
$EDITOR .rhiza/template.yml
# Preview what would be added (validating dry-run)
rhiza sync --strategy diff
# Sync templates
rhiza sync
# Review the imported files
git status
# Commit the changes
git add .
git commit -m "chore: initialize project with rhiza templates"# Navigate to your project
cd existing-project
# Update templates
rhiza sync
# Review changes
git diff
# Commit if satisfied
git add .
git commit -m "chore: update rhiza templates"Edit .rhiza/template.yml:
template-repository: myorg/my-templates
template-branch: production
include:
- .github/workflows
- pyproject.toml
- Makefile
- docker-compose.yml
exclude:
- .github/workflows/experimental.ymlThen sync:
rhiza syncEdit .rhiza/template.yml:
template-repository: mygroup/python-templates
template-host: gitlab
template-branch: main
include:
- .gitlab-ci.yml
- .editorconfig
- .gitignore
- Makefile
- pytest.iniThen sync:
rhiza sync- Python 3.11 or higher
uvpackage manager (recommended) orpip- Git
# Clone the repository
git clone https://github.com/jebel-quant/rhiza-cli.git
cd rhiza-cli
# Install dependencies
make install
# Run tests
make test
# Run linters and formatters
make fmt
# Generate documentation
make docs# Run all tests with coverage
make test
# Run specific test file
pytest tests/test_cli.py
# Run with verbose output
pytest -vThe project uses:
- Ruff for linting and formatting
- pytest for testing
- pre-commit hooks for automated checks
# Run all quality checks
make fmt
# Run dependency checks
make deptry# Generate API documentation
make docs
# Build complete documentation book
make bookThe project includes a comprehensive Makefile for common development tasks:
Bootstrap
install-uv ensure uv/uvx is installed
install-extras run custom build script (if exists)
install install
clean clean
Development and Testing
test run all tests
marimo fire up Marimo server
marimushka export Marimo notebooks to HTML
deptry run deptry if pyproject.toml exists
Documentation
docs create documentation with pdoc
book compile the companion book
fmt check the pre-commit hooks and the linting
all Run everything
Releasing and Versioning
bump bump version
release create tag and push to remote with prompts
post-release perform post-release tasks
Meta
sync sync with template repository as defined in .rhiza/template.yml
help Display this help message
customisations list available customisation scripts
update-readme update README.md with current Makefile help output
Run make help to see this list in your terminal.
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
If you find a bug or have a feature request, please open an issue on GitHub.
This project follows a Code of Conduct. By participating, you are expected to uphold this code.
This project is licensed under the MIT License - see the LICENSE file for details.
- PyPI: https://pypi.org/project/rhiza/
- Repository: https://github.com/jebel-quant/rhiza-cli
- Issues: https://github.com/jebel-quant/rhiza-cli/issues
- Documentation: Generated with
make docs - Companion Book: https://jebel-quant.github.io/rhiza-cli/ (includes coverage report, API docs, and notebooks)
Rhiza follows a modular architecture:
src/rhiza/
├── __init__.py # Package initialization
├── __main__.py # Entry point for python -m rhiza
├── cli.py # Typer app and CLI command definitions
├── models/ # Data models (RhizaTemplate, TemplateLock, …)
└── commands/ # Command implementations
├── __init__.py
├── sync.py # Sync templates (primary command)
└── summarise.py # Summarise template/bundle contents
- Thin CLI Layer: Commands in
cli.pyare thin wrappers that delegate to implementations incommands/ - Separation of Concerns: Each command has its own module with focused functionality
- Type Safety: Uses
pathlib.Pathfor file operations and Typer for type-checked CLI arguments - Clear Logging: Uses
logurufor structured, colored logging output - Validation First: Always validates configuration before performing operations
Ensure the package is installed and your Python scripts directory is in your PATH:
pip install --user rhiza
# Add ~/.local/bin to PATH if needed
export PATH="$HOME/.local/bin:$PATH"Check that:
- Your
.rhiza/template.ymlfile exists - The YAML syntax is valid
- Required fields (
template-repositoryandinclude) are present - The repository format is
owner/repo
Run rhiza sync for detailed error messages — it validates the configuration before syncing.
Ensure:
- The template repository exists and is accessible
- The specified branch exists
- You have network connectivity to GitHub or GitLab
- The repository is public (or you have appropriate credentials configured — see the Authentication Guide)
- The
template-hostfield matches your repository's hosting platform (defaults to "github")
Check:
- The paths in
includeare correct relative to the template repository root - The paths exist in the specified branch
- Any
excludepatterns are not filtering out wanted files
Q: Can I use Rhiza with private template repositories?
A: Yes. Rhiza fetches templates by running git clone, so any credentials that allow Git to access the repository will work. See the Authentication Guide for step-by-step instructions on configuring GitHub Personal Access Tokens (PATs), SSH keys, and GitLab tokens — for both local development and CI/CD environments.
Q: Does Rhiza support template repositories hosted outside GitHub?
A: Yes! Rhiza supports both GitHub and GitLab repositories. Use the template-host field in your .rhiza/template.yml to specify "github" (default) or "gitlab".
Q: How do I use a GitLab repository as a template source?
A: Add template-host: gitlab to your .rhiza/template.yml file. For example:
template-repository: mygroup/myproject
template-host: gitlab
include:
- .gitlab-ci.yml
- MakefileQ: Can I sync templates from multiple repositories?
A: Not directly. However, you can run rhiza sync multiple times with different configurations, or combine templates manually.
Q: How do I create the .rhiza/template.yml configuration file?
A: Create it by hand in the .rhiza/ directory of your project. At a minimum it needs template-repository and one of include/templates/profiles (see the Configuration section). Run rhiza sync --strategy diff for a validating dry-run to confirm it is correct before applying.
Q: How do I update my project's templates?
A: Run rhiza sync — it applies a 3-way merge so your local changes are preserved.
Q: How do I update rhiza-cli itself?
A: The update method depends on how you installed rhiza:
- Using pip: Run
pip install --upgrade rhiza - Using uvx: No action needed!
uvxautomatically uses the latest version each time you run it. Just run your command:uvx rhiza <command> - From source: Run
git pullin the repository directory and thenpip install -e .again
Q: Can I customize which files are included?
A: Yes, edit the include and exclude lists in .rhiza/template.yml to control exactly which files are copied.
Rhiza is developed and maintained by the Jebel Quant team as part of their effort to standardize Python project configurations across their portfolio.