Skip to content

cli-reference.md

Latest commit

 

History

History
220 lines (162 loc) · 7.93 KB

cli-reference.md

File metadata and controls

220 lines (162 loc) · 7.93 KB
Raw
title r2x-cli CLI Reference

r2x-cli CLI Reference

This page is a compact overview of the r2x-cli command surface. Run r2x --help for the complete command tree and r2x <command> --help for command-specific options.

Workflow-specific plugin options, parser settings, pipeline configuration, and application configuration are intentionally not documented here. See the relevant plugin or workflow documentation for those details.

Common commands

Goal Command
Show the installed version r2x --version
Initialize a workspace file r2x init
Install a plugin r2x install <package>
List installed plugins r2x list
Run a target r2x run <target>
Inspect a system r2x read <file>
Update a standalone installation r2x self update

Plugins

The common plugin commands are:

r2x install <package>
r2x install -e <path>
r2x list
r2x remove <package>
r2x sync
r2x sync --upgrade
r2x clean --yes

See Plugin management for package sources and plugin lifecycle guidance.

Run

r2x run accepts either a direct plugin reference or a file and target name. Plugin-specific arguments are passed through after the target.

# Direct plugin mode
r2x run <plugin-ref> [PLUGIN_OPTIONS...]

# File and named-target mode
r2x run <file.yaml> <name>

Common file and named-target options:

Option Purpose
--list List available targets in the file.
--print Print the resolved target without executing it.
-n, --dry-run Print the named pipeline flow without executing or validating plugin packages/configs.
-o, --output <file> Write output to a file instead of stdout.
--zip Save file-mode output as an infrasys ZIP archive.
--pdb Open Python post-mortem debugging after an uncaught plugin failure.

Dry-run still resolves each step against the discovery manifest; unknown or ambiguous references fail before execution.

Direct plugin options include:

r2x run <plugin-ref> --help
r2x run <plugin-ref> --<option> <value>
r2x run <plugin-ref> --input <file>
r2x run <plugin-ref> --output <file>
r2x run <plugin-ref> --repeat <N> --benchmark
r2x run <plugin-ref> --pdb --input <file>

Plugin help marks mandatory options as [required] and separates them from shared run options.

Pass plugin option values as separate arguments. Option names accept both kebab-case and snake_case spellings.

--pdb requires an interactive terminal. Use --input <file> when debugging a plugin so stdin remains available for debugger commands.

Read

In interactive mode, r2x read prints a system overview before opening IPython for the system artifact:

r2x read <file.json>
r2x read <file.zip> --zip
r2x read --exec <script.py> <file.json>
r2x read --exec <script.py> --interactive <file.json>

Use sys.info() in the session to print the overview again. When no file is provided, JSON can be read from stdin:

cat system.json | r2x read

To pipe plugin output into r2x read, replace PLUGIN_REF with an installed plugin reference and omit -o so JSON is written to stdout:

r2x run PLUGIN_REF | r2x read

Use -o <file> to save output to a file, then pass that file to r2x read.

Use --no-banner to suppress the interactive startup banner.

Runtime commands

The runtime commands manage the Python interpreter and virtual environment used by plugins:

r2x python show
r2x python install
r2x python install <version>
r2x python path

r2x venv create --yes
r2x venv path
r2x venv path <new-path>

Update

Standalone installer users can update in place:

r2x self update
r2x self update --dry-run
r2x self update <version>

The upgrade alias is also available:

r2x self upgrade

Installations managed by Cargo, Homebrew, or another package manager should be updated with that package manager.

Global options

These options can be used with commands that support the shared CLI options:

Option Purpose
-q, --quiet Reduce informational output. Repeat as -qq to suppress plugin stdout.
-v, --verbose Increase diagnostic output. Repeat as -vv for trace output.
--log-python Show Python logs on the console.
--no-stdout Do not write captured plugin stdout to the log.

Help

Use the built-in help for the complete surface, including configuration and logging commands that are intentionally outside this compact reference:

r2x --help
r2x <command> --help

Source contracts

The command contracts in this guide were checked against current main. Inspect the pinned root commands and run argument definitions for exact parser types and defaults. Use the installed binary's help when working with a different release. --repeat accepts a positive integer and defaults to 1. Direct plugin execution reads JSON from stdin unless --input is supplied and writes its result to stdout unless --output is supplied. Plugin-specific required values, types, and defaults come from the discovered plugin contract. Invalid arguments, discovery failures, and plugin failures report diagnostics and exit unsuccessfully.

Pipeline configuration

The tested fixture uses these top-level fields:

Field Meaning
pipelines Map of pipeline names to ordered plugin-reference lists.
config Map from plugin references to per-plugin configuration values.
variables Optional substitutions resolved in configuration values.
output_folder Optional default output folder passed into plugin configuration handling.

--list reads names and ordered steps from the YAML. --print resolves and displays the selected pipeline's settings. --dry-run displays flow only; it does not run the package/configuration validation used by actual execution. The executing path verifies plugins, validates their configurations, and then invokes steps in order. See the source dispatcher and configuration schema.

Tutorial plugin contracts

These are real APIs in the shipped r2x-tutorial fixture, not application-specific model APIs:

These lines are signature notation, not executable calls.

CreateDemo.from_context(ctx: PluginContext[CreateConfig]) -> Plugin[CreateConfig]
scale_values(system: System, config: ScaleConfig) -> Result[System, str]
Configuration Field Type/default Behavior
CreateConfig name str = "demo" Name of the newly built system.
ScaleConfig factor float = 2, strictly positive Multiplies the values of existing Item components.

create returns a context containing a new system with two components, initially valued 10 and 20. scale_values mutates that system and returns it in Ok; its configuration rejects zero or negative factors. The transform does not perform a model-schema translation and does not add electrical meaning to the fixture's numeric values. The entry-point group determines the runtime role; explicit r2x.parsers and r2x.transforms groups avoid legacy name-based role inference. See the fixture implementation and runtime role mapping.