r2x

Plugin manager and pipeline runner for the r2x
power systems modeling ecosystem.

Installation · Upgrading · Quick Start · Plugins · Pipelines · Shell · Architecture · Ecosystem · Source · License

The r2x CLI is the orchestrator for the r2x ecosystem. It discovers installed Python plugins, chains them into pipelines, and manages Python environments, all from a single Rust binary.

Plugins handle every step of a power systems translation workflow: parsing source models, applying transforms, translating between formats, and exporting to targets like PLEXOS or Sienna. The CLI finds them via static analysis (no Python import side effects), resolves their dependencies, and pipes each step's output into the next.

Installation

Download the latest binary from the releases page, or use the one-liner installers below.

macOS / Linux

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/NatLabRockies/r2x-cli/releases/latest/download/r2x-installer.sh | sh

Windows

powershell -ExecutionPolicy Bypass -c "irm https://github.com/NatLabRockies/r2x-cli/releases/latest/download/r2x-installer.ps1 | iex"

Verify it works:

r2x --version

Note

Pre-built binaries require Python shared libraries at runtime. If r2x --version fails with a missing libpython error, run uv python install 3.12 to make the shared library available.

Upgrading

If you installed via the shell/powershell installer, a standalone updater is included:

r2x-update

Alternatively, re-run the installer to get the latest version:

# macOS / Linux
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/NatLabRockies/r2x-cli/releases/latest/download/r2x-installer.sh | sh

Quick Start

# 1. Scaffold a pipeline config
r2x init

# 2. Install a plugin from PyPI
r2x install r2x-reeds

# 3. See what got installed
r2x list

# 4. Run a pipeline
r2x run pipeline.yaml reeds-test

r2x init creates a pipeline.yaml with example variables, pipeline definitions, and per-plugin configuration. Edit it to match your data and you are running translations in under a minute.

Plugin Management

Command	What it does
`r2x install <package>`	Install from PyPI
`r2x install gh:NatLabRockies/r2x-reeds`	Install from a GitHub repo
`r2x install gh:NatLabRockies/r2x-reeds --branch dev`	Install a specific branch (`--tag`, `--commit`)
`r2x install -e /path/to/plugin`	Install in editable mode for local dev
`r2x remove <package>`	Uninstall a plugin
`r2x list`	List all installed plugins
`r2x list r2x-reeds`	Filter by package name
`r2x list r2x-reeds break-gens`	Filter by package and module
`r2x sync`	Re-run plugin discovery and refresh manifest metadata
`r2x sync --upgrade`	Upgrade compatible installed plugins, then sync and show version/commit changes
`r2x clean -y`	Wipe the plugin manifest and clean cache

Tip

Plugin discovery uses static analysis (ast-grep) instead of importing Python modules. This makes r2x sync and r2x install fast and safe, with no side effects from plugin code.

Running Pipelines

Pipelines chain plugins together in a named sequence defined in a YAML file. See Pipeline File Format for the full spec.

# List available pipelines
r2x run pipeline.yaml --list

# Dry run (preview without executing)
r2x run pipeline.yaml my-pipeline --dry-run

# Execute
r2x run pipeline.yaml my-pipeline

# Execute and save output
r2x run pipeline.yaml my-pipeline -o output.json

Running Plugins Directly

Skip the pipeline and run a single plugin with inline arguments:

# Run a plugin directly
r2x run plugin r2x-reeds.reeds-parser solve_year=2030 weather_year=2012

# Show a plugin's help
r2x run plugin r2x-reeds.reeds-parser --show-help

# List all runnable plugins
r2x run plugin

Pipeline File Format

Pipeline configs are YAML with three sections: variables for substitution values, pipelines for named plugin sequences, and config for per-plugin settings.

variables:
  output_dir: "output"
  reeds_run: /path/to/reeds/run
  solve_year: 2032

pipelines:
  reeds-test:
    - r2x-reeds.reeds-parser
    - r2x-reeds.break-gens

  reeds-to-plexos:
    - r2x-reeds.reeds-parser
    - r2x-reeds-to-plexos.reeds-to-plexos
    - r2x-plexos.plexos-exporter

config:
  r2x-reeds.reeds-parser:
    weather_year: 2012
    solve_year: ${solve_year}
    path: ${reeds_run}

  r2x-reeds.break-gens:
    drop_capacity_threshold: 5

  r2x-plexos.exporter:
    output: ${output_dir}

output_folder: ${output_dir}

Variables use ${var} syntax and are substituted at runtime across all config values and output_folder.

Interactive System Shell

Load a system JSON and drop into an IPython session for exploration:

r2x read system.json

The session exposes sys (the loaded system), plugins (installed plugins), and lazy-loaded pd, np, plt for pandas, numpy, and matplotlib. Type %r2x_help for the full list of magic commands.

Additional read options

# From stdin
cat system.json | r2x read

# Run a script against the system
r2x read system.json --exec script.py

# Run a script then stay interactive
r2x read system.json --exec script.py -i

Configuration

# Show current config
r2x config show

# Set values
r2x config set python-version 3.13
r2x config set cache-path /path/to/cache

# Reset everything
r2x config reset -y

Python and virtual environment management

The r2x python command provides shortcuts for Python runtime management:

# Install a Python version
r2x python install 3.13

# Show installed Python versions
r2x python show

# Get the Python executable path
r2x python path

# Create or recreate the managed venv
r2x config venv create -y

# Install packages into the managed venv
uv pip install <package> --python $(r2x python path)

[!TIP] The r2x python commands are shortcuts for r2x config python <action>. Both work identically.

Cache management

r2x config cache clean

Logging preferences

# Show current logging settings
r2x log show

# Keep Python/plugin stdout out of the log file by default
r2x log set no-stdout true

# Cap log file size (bytes)
r2x log set max-size 26214400

# Show Python log messages on console by default
r2x log set log-python true

# Override log file location
r2x log path /tmp/r2x.log

# Print the resolved log file path
r2x log path

# Command help
r2x log --help
r2x log set --help

Note

Configuration is stored in ~/.config/r2x/config.toml on Unix-like systems or %APPDATA%\r2x\config.toml on Windows. Override with the R2X_CONFIG environment variable.

Verbosity

Flag	Effect
`-q`	Suppress informational logs
`-qq`	Suppress logs and plugin stdout
`-v`	Debug logging
`-vv`	Trace logging
`--log-python`	Show Python logs on console
`--no-stdout`	Do not capture plugin stdout in logs

Persisted logging defaults can be set with r2x log set ....

Architecture

flowchart LR
    CLI[r2x CLI] --> Config[r2x-config]
    CLI --> Manifest[r2x-manifest]
    CLI --> AST[r2x-ast]
    CLI --> Python[r2x-python]
    CLI --> Logger[r2x-logger]
    AST -->|ast-grep| Discovery[Plugin Discovery]
    Python -->|PyO3| Runtime[Python Runtime]
    Manifest --> Plugins[(Plugin Registry)]

The workspace is split into six crates:

Crate	Role
`r2x-cli`	CLI entry point, command routing, pipeline execution
`r2x-config`	Configuration management, paths, Python/venv settings
`r2x-manifest`	Plugin manifest read/write, package metadata
`r2x-ast`	AST-based plugin discovery via ast-grep
`r2x-python`	PyO3 bridge for running Python plugins
`r2x-logger`	Structured logging with tracing

Ecosystem

The r2x ecosystem is a set of independently published packages. The CLI orchestrates them; r2x-core provides the shared plugin framework; model packages supply parsers, exporters, and data models; and translation packages convert between formats.

Package	Description
r2x-cli (this repo)	Rust CLI that discovers, installs, and runs any r2x plugin. Chains plugins into pipelines and manages Python environments
r2x-core	Shared plugin framework: `PluginContext`, `Rule`, `System`, `@getter` registry
R2X	Translation plugins: ReEDS to PLEXOS, Sienna to PLEXOS, and more
r2x-reeds	ReEDS parser, transform plugins, and component models
r2x-plexos	PLEXOS parser/exporter and component models
r2x-sienna	Sienna parser/exporter and PowerSystems.jl-compatible models
infrasys	Foundational `System` container, time series management, and component storage
plexosdb	Standalone PLEXOS XML database reader/writer

Building from Source

Prerequisites

Rust toolchain (rustup)
uv package manager
Python 3.11, 3.12, or 3.13

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.12

Important

Restart your shell after installing rustup and uv so both are available in your PATH.

Build and install

git clone https://github.com/NatLabRockies/r2x-cli && cd r2x-cli
PYO3_PYTHON=$(uv python find 3.12) cargo install --path crates/r2x-cli --force --locked

This places the r2x binary in ~/.cargo/bin/.

r2x --version

Manual build (custom install path)

PYO3_PYTHON=$(uv python find 3.12) cargo build --release

The binary lands at target/release/r2x. Copy it wherever you like.

Development workflow

The project uses a justfile for common tasks:

just build     # fmt + clippy + build
just test      # cargo test --workspace --all-features
just lint      # fmt + clippy
just all       # fmt + clippy + test

Troubleshooting

If the build fails with a Python error, verify uv python find 3.12 returns a valid path. You may need uv python install 3.12 first.
If r2x is not found after install, check that ~/.cargo/bin is in your $PATH.
On HPC systems with older glibc, building from source is usually required since pre-built binaries target glibc 2.28+.

License

BSD-3-Clause. See LICENSE.txt for the full text.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

r2x

Installation

macOS / Linux

Windows

Upgrading

Quick Start

Plugin Management

Running Pipelines

Running Plugins Directly

Pipeline File Format

Interactive System Shell

Configuration

Verbosity

Architecture

Ecosystem

Building from Source

Prerequisites

Build and install

License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

r2x

Installation

macOS / Linux

Windows

Upgrading

Quick Start

Plugin Management

Running Pipelines

Running Plugins Directly

Pipeline File Format

Interactive System Shell

Configuration

Verbosity

Architecture

Ecosystem

Building from Source

Prerequisites

Build and install

License