rpr-cli 0.3.1

RPR CLI -- React Python Rust monorepo scaffolding orchestrator

RPR CLI

React Python Rust monorepo scaffolding orchestrator.

Installation

Published package name: rpr-cli

Once published to PyPI, install by name with either:

uv add rpr-cli
uv tool install rpr-cli

Both install the rpr command.

For development, editable install is fine:

uv tool install -e .

For an actual distributable install you can use in other projects, build the wheel first and install the built artifact:

uv build
uv tool install dist/rpr_cli-*.whl

From another local project you can also install the built artifact directly:

uv add ../project-getting-started/dist/rpr_cli-*.whl

Usage

🚀 Scaffolding & Generation

Create a new NX + UV monorepo, then add apps and packages as needed.

NX monorepo uses integrated mode.

rpr init my-app              # Create/init my-app with root NX + UV tooling and AI instructions
cd my-app
rpr generate domain my-app   # Add a Python domain package
rpr generate api my-app      # Add a FastAPI application
rpr generate ui my-app       # Add a React UI library and web app
rpr generate engine my-app   # Add a Rust/PyO3 computation engine
rpr generate storybook       # Add Storybook for UI component development

rpr init <project-name> creates the project directory when it does not exist. If the directory already exists and is not an NX workspace, RPR initializes Git and runs nx init inside that directory.

By default, rpr init scaffolds the root workspace and AI instructions only. To create project components during initialization, repeat --scaffold or pass a comma-separated list:

rpr init todo-list --scaffold common
rpr init todo-list --scaffold domain
rpr init todo-list --scaffold api --domain-migrations
rpr init todo-list --scaffold api --scaffold web --domain-migrations

Available scaffolds are:

• common: Alias for instructions, domain, api, ui, web, and storybook; excludes engine.
• instructions: AI instruction files for Cursor, Copilot, Claude Code, and Gemini.
• domain: Python DDD package at packages/python/domain.
• api: FastAPI app at apps/<name>-api; also scaffolds domain.
• ui: React UI library at packages/node/<name>-ui.
• web: React web app at apps/<name>-web; also scaffolds ui.
• storybook: Storybook host package; requires or scaffolds ui.
• engine: Rust/PyO3 package at packages/python/<name>-engine.

Dependency Placement

RPR keeps dependencies close to the package that uses them.

• Root Python tooling such as Ruff, pytest, pyright, pre-commit, and maturin lives in the root pyproject.toml.
• Domain runtime dependencies such as sqlmodel, asyncpg, pydantic-settings, and optional alembic are added to packages/python/domain/pyproject.toml.
• API runtime dependencies such as fastapi, uvicorn, and the workspace domain package are added to apps/<name>-api/pyproject.toml.
• Node dependencies are written to the relevant package-level package.json files, and npm install runs from the root workspace.

Python dependency changes are made with uv so they are tracked in pyproject.toml. Node dependency changes are made through npm workspace package metadata and root npm install.

Update project-owned package manifests from upstream registries with rpr update node or rpr update python. Node updates target package.json; Python updates target pyproject.toml by default and fall back to requirements.txt when no pyproject.toml exists. Use --file to update a nested manifest, --dry-run to preview without changing files or running installers, and --include-major to opt into major-version updates.

The scaffold version manifest that powers generated dependency specs and the synced AI tech-stack overview lives in src/rpr/dependency_manifest_data.py. Refresh it from upstream registries with rpr refresh manifest when you want the repo-owned defaults to move forward.

🧠 AI Instructions & Code Templates

Sync project context to your favorite AI tools and add common code patterns.

rpr sync rules                         # Sync AI instructions to Cursor, Copilot, Claude Code, and Gemini
rpr add template python mapper_util    # Add a Python code template to your project
rpr add template python camel_case_model
rpr add template node sticky_navigation --include-tests
rpr add template node -l               # List available Node/TSX templates
rpr add template --list                # List all available code templates

Use --output-dir to write generated files to a different directory while keeping the template filenames. Templates with test companions can use --include-tests; Node browser-test templates print the extra npm dev dependencies and any Playwright setup notes they need. Existing config files such as vitest.config.ts are not merged automatically; RPR leaves them unchanged unless you rerun with --force to replace them.

💬 Interactive Shell

rpr chat is the primary interactive shell for the product. It runs a Rich-based session with slash commands for both chat controls and existing CLI workflows.

rpr chat                                 # Start the interactive shell
rpr chat --approval-mode auto-readonly   # Override the session approval mode

Inside the shell:

/help        List supported slash commands
/settings    Inspect and update persisted settings in-shell
/init        Run workspace bootstrap from chat
/generate    Run scaffolding commands from chat
/sync        Sync AI instructions from chat
/add         Add a registered template from chat
/check       Run workspace health checks from chat
/map         Generate a code map from chat
/exit        End the session

There is no separate --tui mode. The unified shell is the default chat experience.

🛠️ Maintenance & Insights

Keep your project healthy and explore its structure.

rpr refresh manifest         # Refresh the scaffold dependency manifest from npm, PyPI, and crates.io
rpr update node              # Update package.json dependencies and run npm install
rpr update python            # Update pyproject.toml or requirements.txt and sync Python dependencies
rpr check                    # Inspect project health and report setup status
rpr map                      # Generate a structured code map of your project
rpr settings                 # Inspect persisted shell settings
rpr settings set theme ocean # Update the terminal theme
rpr settings set approval_mode auto-all
rpr settings set startup_help false

Persisted settings currently include:

• theme: Rich console theme
• approval_mode: default chat approval mode (ask, auto-readonly, auto-all)
• startup_help: whether chat shows slash-command guidance on startup

rpr refresh manifest is a repo-maintenance command. It rewrites src/rpr/dependency_manifest_data.py, which feeds scaffold dependency versions in rpr generate ... and the versioned overview text produced by rpr sync rules. Use --dry-run to preview the manifest rewrite without writing the file.

rpr update node and rpr update python are project-maintenance commands. They update the selected package manifest, print applied and held-back dependency changes, and run the matching installer only when live changes are written. Without --include-major, RPR chooses the latest stable version inside the current major version and reports higher-major candidates as held back. Python updates cover [project].dependencies, [dependency-groups].*, and requirements.txt; build backend packages in [build-system].requires are left unchanged unless a future explicit build-system update option is added.

⚙️ Common Flags

Most commands support these global flags:

• --dry-run: Preview changes without writing any files.
• --help: Show detailed help for any command or subcommand.

Example:

rpr init my-app --scaffold domain --dry-run
rpr generate api my-app --dry-run

Dry runs print the commands RPR would execute, the files/directories it would create or update, and the package dependencies it would add with their target scope.

The check command also supports:

• --json: Output machine-readable JSON for CI/CD integration.

The chat command also supports:

• --provider: Override the AI provider. The mock provider is the only supported provider today.
• --model: Override the active model name.
• --approval-mode: Override the session approval mode without changing persisted settings.

Project Development

Setup

# Install Python dependencies
uv sync

# Build the Rust extension (rpr_parser) — required for rpr map acceleration
cd rpr-parser && uv run maturin develop && cd ..

Note: uv tool install dist/rpr-*.whl uses the root hatchling build backend and does not build the Rust extension. You must run maturin develop separately before using rpr map with the Rust backend. Without it, rpr map falls back to the pure-Python implementation automatically.

Running Tests

# Full test suite (Python)
uv run pytest

# Single test file
uv run pytest tests/test_map_extractor.py

# Single test
uv run pytest tests/test_map_extractor.py::test_fallback_returns_correct_shape

# Rust unit tests (rpr_parser crate)
cd rpr-parser && cargo test && cd ..

# Lint and format
uv run ruff check .
uv run ruff format .

The Rust-path tests in tests/test_map_extractor.py are automatically skipped if the Rust extension hasn't been built yet — run maturin develop first to enable them.

Publishing To PyPI

This repo is set up to publish the package rpr-cli to PyPI from GitHub Actions.

One-time setup:

1. Create the PyPI project rpr-cli.
2. Create a PyPI Trusted Publisher for this repository using workflow .github/workflows/publish-pypi.yml and environment pypi.

No PYPI_API_TOKEN secret is required when publishing through GitHub Actions OIDC.

Release flow:

# update src/rpr/__init__.py with the new version
git commit -am "Release 0.1.2"
git tag v0.1.2
git push origin main --tags

The workflow in .github/workflows/publish-pypi.yml builds the sdist and wheel, checks that the tag matches the package version, and uploads dist/* to PyPI.