CLI.md

RPO CLI Reference

The rpo-cli crate provides batch execution and shell-composable commands for mission planning, validation, and Monte Carlo analysis. It wraps the same rpo-core pipeline used by rpo-api.

Output

Porcelain commands output a markdown summary to stdout by default. Use --json for machine-readable JSON. Use -o <path> to write to a file instead of stdout. Progress and status messages go to stderr.

Plumbing commands always output JSON to stdout.

# Summary to stdout (default)
cargo run -p rpo-cli -- mission -i examples/mission.json

# JSON to stdout (pipe to jq, etc.)
cargo run -p rpo-cli -- mission -i examples/mission.json --json

# Write to file
cargo run -p rpo-cli -- mission -i examples/mission.json -o report.md
cargo run -p rpo-cli -- mission -i examples/mission.json --json -o report.json

Commands

Porcelain

mission

End-to-end analytical mission: classification, Lambert transfer, perch handoff, waypoint targeting, safety, covariance, eclipse.

Flag	Type	Default	Description
-i, --input	path	required	JSON input file (PipelineInput)
--json	bool	false	Output JSON instead of markdown summary
-o, --output	path	none	Write output to file instead of stdout
--cola-threshold	f64	none	Target miss distance for collision avoidance (km). Enables COLA
--cola-budget	f64	0.01	Maximum delta-v budget for COLA (km/s). Requires --cola-threshold
--auto-enrich	bool	false	Enable formation design enrichment with 0.1 km separation threshold
--auto-enrich-threshold	f64	none	Custom min separation (km) for formation design. Implies --auto-enrich

Free-drift (abort-case) analysis and closest-approach refinement (Brent's method on range rate) are included automatically when config.safety is present in the input.

COLA auto-compute: When config.safety is present and any POCA violates min_distance_3d_km, collision avoidance maneuvers are automatically computed using the safety threshold as the target distance and a default budget of 10 m/s. The --cola-threshold and --cola-budget flags override this auto-derived config. Post-avoidance multi-leg verification detects secondary conjunctions (where an avoidance maneuver on one leg creates a new violation on a downstream leg). Legs where COLA fails (budget exceeded, degenerate geometry) are reported as skipped.

Formation design: When --auto-enrich is set, the pipeline computes an enrichment suggestion (safe e/i vectors per D'Amico Eq. 2.22) and applies it to the perch ROE before waypoint targeting. Per-waypoint enrichment advisory and per-leg transit e/i separation profiles are computed and displayed alongside the standard mission output. The API equivalent returns both baseline and enriched plans for instant toggling.

cargo run -p rpo-cli -- mission -i examples/mission.json
cargo run -p rpo-cli -- mission -i examples/mission.json --json
cargo run -p rpo-cli -- mission -i examples/mission.json --cola-threshold 0.3 --cola-budget 0.01
cargo run -p rpo-cli -- mission -i examples/mission.json --auto-enrich
cargo run -p rpo-cli -- mission -i examples/mission.json --auto-enrich-threshold 0.15 --json

validate

Mission planning + nyx high-fidelity validation. Compares analytical trajectories against full-physics propagation (J2, drag, SRP with eclipses, Sun/Moon third-body). Requires network on first run to download ANISE ephemeris kernels (~50 MB, cached).

Flag	Type	Default	Description
-i, --input	path	required	JSON input file (PipelineInput with spacecraft configs)
--json	bool	false	Output JSON instead of markdown summary
-o, --output	path	none	Write output to file instead of stdout
--samples-per-leg	u32	50	Comparison points per leg
--auto-drag	bool	false	Auto-derive differential drag rates from spacecraft properties via nyx
--cola-threshold	f64	none	Target miss distance for collision avoidance (km). Enables COLA
--cola-budget	f64	0.01	Maximum delta-v budget for COLA (km/s). Requires --cola-threshold
--auto-enrich	bool	false	Enable formation design enrichment with 0.1 km separation threshold
--auto-enrich-threshold	f64	none	Custom min separation (km) for formation design. Implies --auto-enrich

cargo run -p rpo-cli -- validate -i examples/validate.json --auto-drag
cargo run -p rpo-cli -- validate -i examples/validate.json --json
cargo run -p rpo-cli -- validate -i examples/validate.json --auto-drag --cola-threshold 0.3
cargo run -p rpo-cli -- validate -i examples/validate.json --auto-enrich

mc

Full-physics Monte Carlo ensemble analysis. Requires monte_carlo config in the input JSON. Uses rayon for parallel sample execution.

Flag	Type	Default	Description
-i, --input	path	required	JSON input file (PipelineInput with spacecraft + MC configs)
--json	bool	false	Output JSON instead of markdown summary
-o, --output	path	none	Write output to file instead of stdout
--auto-drag	bool	false	Auto-derive differential drag rates before MC
--cola-threshold	f64	none	Target miss distance for collision avoidance (km). Enables COLA
--cola-budget	f64	0.01	Maximum delta-v budget for COLA (km/s). Requires --cola-threshold
--auto-enrich	bool	false	Enable formation design enrichment with 0.1 km separation threshold
--auto-enrich-threshold	f64	none	Custom min separation (km) for formation design. Implies --auto-enrich

cargo run -p rpo-cli -- mc -i examples/mc.json --auto-drag
cargo run -p rpo-cli -- mc -i examples/mc.json --json
cargo run -p rpo-cli -- mc -i examples/mc.json --auto-drag --auto-enrich

Plumbing

All plumbing commands take -i, --input <path> and produce JSON to stdout.

classify

Classify chief/deputy separation as proximity or far-field.

Input: { chief: StateVector, deputy: StateVector, proximity?: ProximityConfig }

cargo run -p rpo-cli -- classify -i examples/classify.json

transfer

Solve Lambert transfer between two ECI states. TOF is derived from the epoch difference.

Input: { departure: StateVector, arrival: StateVector, config?: LambertConfig }

cargo run -p rpo-cli -- transfer -i examples/transfer.json

convert

Convert ECI state to Keplerian elements.

Input: bare StateVector { epoch, position_eci_km, velocity_eci_km_s }

cargo run -p rpo-cli -- convert -i examples/convert.json --to keplerian

propagate

Propagate ROE state via J2 or J2+drag STM.

Input: { roe: ROE, chief_mean: KeplerianElements, epoch: string, dt_s: number, propagator?: "j2" }

cargo run -p rpo-cli -- propagate -i examples/propagate.json

roe

Compute quasi-nonsingular ROE between chief and deputy states.

Input: { chief: StateVector, deputy: StateVector }

cargo run -p rpo-cli -- roe -i examples/roe.json

safety

Analyze passive safety metrics (e/i separation, 3D keep-out) for a planned mission.

Input: full PipelineInput (same as mission command).

cargo run -p rpo-cli -- safety -i examples/mission.json

eclipse

Compute eclipse intervals along a planned mission trajectory.

Input: full PipelineInput (same as mission command).

cargo run -p rpo-cli -- eclipse -i examples/mission.json

Input Format

All porcelain commands accept a PipelineInput JSON file. This is the same type used by the WebSocket API (MissionDefinition). See docs/schema/pipeline-input.schema.json for the full JSON Schema.

Example files in examples/:

File	Used by
mission.json	mission, safety, eclipse
validate.json	validate
mc.json	mc
classify.json	classify
transfer.json	transfer
convert.json	convert
propagate.json	propagate
roe.json	roe

Spacecraft Presets

The chief_config and deputy_config fields accept a named preset or custom properties:

"chief_config": "servicer_500kg"

"chief_config": "cubesat_6u"

"chief_config": {
  "custom": {
    "dry_mass_kg": 500.0,
    "drag_area_m2": 1.0,
    "coeff_drag": 2.2,
    "srp_area_m2": 1.0,
    "coeff_reflectivity": 1.8
  }
}

Preset	Mass	Drag Area	Cd	SRP Area	Cr
cubesat_6u	12 kg	0.06 m2	2.2	0.06 m2	1.5
servicer_500kg	500 kg	1.0 m2	2.2	1.0 m2	1.5

These configs are required for validate, mc, and --auto-drag. If omitted, validate defaults to servicer_500kg; mc and drag extraction return an error.

Shell Completions

cargo run -p rpo-cli -- completions bash > /usr/local/etc/bash_completion.d/rpo-cli
cargo run -p rpo-cli -- completions zsh > ~/.zfunc/_rpo-cli
cargo run -p rpo-cli -- completions fish > ~/.config/fish/completions/rpo-cli.fish