r2x-cli

A comprehensive framework plugin manager for the r2x power systems modeling ecosystem. Simplifies discovery, installation, and management of r2x framework plugins.

Features

• Easy plugin management
• Built-in package resolution
• Python integration support

Building from Source

Prerequisites

Before building r2x-cli, you need:

1. Rust toolchain - Install via rustup:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

   Follow the prompts and choose the default installation method.

2. UV package manager - Install via:

   curl -LsSf https://astral.sh/uv/install.sh | sh

3. Python 3.11, 3.12, or 3.13 - Install via uv:

   uv python install 3.12

After installation, restart your shell to ensure the tools are in your PATH.

Build Steps

Step 1: Clone and Build

Clone the repository:

# For users (HTTPS)
git clone https://github.com/NREL/r2x-cli && cd r2x-cli

# For developers (SSH)
git clone [email protected]:NREL/r2x-cli.git && cd r2x-cli

Set the PYO3_PYTHON environment variable to point to your Python installation. This is required for the PyO3 bindings to find the correct Python interpreter:

# Find your Python installation path
uv python list

# Linux example:
export PYO3_PYTHON=~/.local/share/uv/python/cpython-3.12.11-linux-x86_64-gnu/bin/python3.12

# macOS example:
export PYO3_PYTHON=~/.local/share/uv/python/cpython-3.12.11-macos-aarch64-none/bin/python3.12

# Windows example (PowerShell):
$env:PYO3_PYTHON = "$env:USERPROFILE\.local\share\uv\python\cpython-3.12.11-windows-x86_64-none\python.exe"

Build in release mode:

cargo build --release

The binary will be available at target/release/r2x (or target/release/r2x.exe on Windows).

Step 2: Install the Binary

Create the r2x binary directory and copy the built binary:

# Linux/macOS
mkdir -p ~/.r2x/bin
cp target/release/r2x ~/.r2x/bin/r2x

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.r2x\bin"
Copy-Item target\release\r2x.exe "$env:USERPROFILE\.r2x\bin\r2x.exe"

Step 3: Link Python Dynamic Library

The r2x-cli binary needs to find the Python shared library at runtime. Create a symbolic link in the binary directory:

Linux:

# Link libpython3.12.so.1.0
ln -s ~/.local/share/uv/python/cpython-3.12.11-linux-x86_64-gnu/lib/libpython3.12.so.1.0 \
      ~/.r2x/bin/libpython3.12.so.1.0

# If the file doesn't exist, check the exact path with:
find ~/.local/share/uv/python -name "libpython*.so*"

macOS:

# Link libpython3.12.dylib
ln -s ~/.local/share/uv/python/cpython-3.12.11-macos-aarch64-none/lib/libpython3.12.dylib \
      ~/.r2x/bin/libpython3.12.dylib

# For Intel Macs, the path may be different:
find ~/.local/share/uv/python -name "libpython*.dylib"

Windows:

# Copy python312.dll (Windows uses DLL instead of symlinks)
Copy-Item "$env:USERPROFILE\.local\share\uv\python\cpython-3.12.11-windows-x86_64-none\python312.dll" `
          "$env:USERPROFILE\.r2x\bin\python312.dll"

Step 4: Update PATH

Add the r2x binary directory to your PATH:

Linux/macOS (bash):

echo 'export PATH="$HOME/.r2x/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Linux/macOS (zsh):

echo 'export PATH="$HOME/.r2x/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Windows (PowerShell):

# Add to user PATH permanently
[Environment]::SetEnvironmentVariable(
    "Path",
    [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\.r2x\bin",
    "User"
)

# For current session only:
$env:PATH = "$env:USERPROFILE\.r2x\bin;$env:PATH"

Step 5: Verify Installation

Test that r2x is working:

r2x --version
r2x --help

You should see the version information and list of available commands.

Troubleshooting Build Issues

Problem: "libpython not found" error

• Verify the symbolic link or DLL copy was created correctly
• Check that the Python library exists at the source path using find (Linux/macOS) or Get-ChildItem (Windows)
• Ensure the Python version in the library filename matches your PYO3_PYTHON version

Problem: Build fails with "PYO3_PYTHON not set"

• Make sure you exported PYO3_PYTHON before running cargo build
• Verify the path points to a valid Python executable: $PYO3_PYTHON --version

Problem: r2x command not found

• Verify ~/.r2x/bin is in your PATH: echo $PATH
• Try using the full path: ~/.r2x/bin/r2x --version
• Make sure you reloaded your shell configuration

HPC/Older Systems: On HPC systems or machines with older glibc versions, building from source is often required because pre-built binaries may be incompatible. Follow the steps above, paying special attention to setting the correct PYO3_PYTHON path for your system's Python installation.

Python Package Management

This project uses uv for handling Python packages. With uv, you don't need to worry about Python or plugin versioning—uv automatically handles dependency resolution and environment isolation for you.

Getting Started

# Initialize a new pipeline file in the current directory
r2x init

# Initialize with custom filename
r2x init my-pipeline.yaml

The r2x init command creates a template pipeline file with:

• Example variables for substitution
• Multiple pipeline examples
• Plugin configuration templates
• Comments explaining all features

You can then edit the file to configure your own pipelines.

Configuration Management

# Show current configuration
r2x config show

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

# View or set config file path
r2x config path                    # Show path
r2x config path /new/config/path   # Set path

# Reset configuration to defaults
r2x config reset -y

Python & Virtual Environment Management

# Install or update Python version
r2x config python install 3.13

# Get the Python executable path (useful for scripting)
r2x config python path

# Show current Python configuration
r2x config python show

# Manage virtual environment
r2x config venv create              # Recreate venv (prompts for confirmation)
r2x config venv create -y/--yes     # Skip confirmation
r2x config venv path                # Show venv path

# Get or set custom venv path
r2x config venv path /path/to/custom/venv

# Automated venv recreation
R2X_VENV_YES=1 r2x config venv create  # Skip confirmation with environment variable

Install packages in your managed venv:

uv pip install <package> --python $(r2x config python path)

Cache Management

# Clean the cache directory
r2x config cache clean

# View or set cache path
r2x config cache path                    # Show path
r2x config cache path /new/cache/path    # Set path

Pipeline Management

# List available pipelines in a file
r2x run pipeline.yaml --list

# Execute a pipeline (explicit path and name)
r2x run pipeline.yaml my-pipeline

# Execute from default pipeline.yaml
r2x run my-pipeline

# Show pipeline structure
r2x run pipeline.yaml my-pipeline --print

# Show pipeline flow without executing (--dry-run)
r2x run pipeline.yaml my-pipeline --dry-run

# Save pipeline output to file
r2x run pipeline.yaml my-pipeline -o output.json

The --dry-run flag displays which plugins produce/consume stdout, helping you understand data flow between pipeline stages before execution.

Plugin Management

# List all installed plugins
r2x list

# Filter by plugin package name
r2x list r2x-reeds

# Filter by module/function name
r2x list r2x-reeds break_gens

# Install a plugin from PyPI
r2x install r2x-reeds

# Install from git repository
r2x install NREL/r2x-reeds

# Install from git with custom host
r2x install --host github.com NREL/r2x-reeds

# Install from specific branch, tag, or commit
r2x install --branch develop NREL/r2x-reeds
r2x install --tag v1.0.0 NREL/r2x-reeds
r2x install --commit abc123 NREL/r2x-reeds

# Install in editable mode (for development)
r2x install -e /path/to/plugin

# Install with cache disabled (force rebuild)
r2x install --no-cache r2x-reeds

# Remove a plugin
r2x remove r2x-reeds

# Sync plugin manifest (refresh plugin discovery)
r2x sync

# Clean plugin manifest (remove all plugins)
r2x clean
r2x clean -y  # Skip confirmation

Running Plugins Directly

# Run a plugin with arguments (key=value format)
r2x run plugin my-plugin key1=value1 key2=value2

# Show plugin help and parameters
r2x run plugin my-plugin --show-help

# Example: Run ReEDS parser
r2x run plugin r2x_reeds.parser \
  store-path=/path/to/reeds/run \
  solve_year=2030 \
  weather_year=2012 \
  case_name=my_scenario

# Pass additional arguments after plugin args
r2x run plugin my-plugin arg1=value1 -- --extra-flag

System Integration

# Load and inspect a JSON system file
r2x read system.json

# Load from stdin and open IPython with system available
cat system.json | r2x read

# Pipe plugin output to read command
r2x run plugin r2x_reeds.parser store-path=/data | r2x read

Verbosity Control

# Quiet mode (suppress info logs)
r2x -q run plugin my-plugin

# Very quiet mode (suppress info and plugin stdout)
r2x -q -q run plugin my-plugin

# Verbose mode (show debug logs)
r2x -v run plugin my-plugin

# Very verbose mode (show trace logs)
r2x -vv run plugin my-plugin

# Enable Python logging
r2x --log-python run plugin my-plugin

License

BSD-3-Clause License. See LICENSE.txt for details.