CLI overview
The command-line interface is the first-class interface for engineers. Everything the HTTP API can do, the CLI can do, and a few things only the CLI does.
orbitforge <COMMAND> [OPTIONS]Commands
| Command | Purpose |
|---|---|
constellation walker | Generate Walker Delta and Walker Star constellations |
import-tle | Import real satellites from a NORAD TLE file |
import-ephem | Import satellites with supplied ephemerides, OEM or SP3 |
design | Synthesize a constellation from a requirements document |
simulate | Propagate over a time range and export results |
eclipse | Compute umbra and penumbra intervals |
link | Link-budget analysis with the ITU-R atmosphere suite |
coverage | Grid coverage and revisit statistics |
platform-access | Access from a fixed site or a moving platform |
maneuver | Propagate a mission with impulsive or finite burns |
target | Solve for burn parameters with a differential corrector |
stationkeep | Station-keeping delta-v and propellant budget |
od bls | Orbit determination by batch least squares |
od ekf | Orbit determination by extended Kalman filter |
od simulate-tracking | Generate synthetic tracking observations |
conjunction screen | Screen for close approaches and collision probability |
stations list | Ground-station catalog |
transfer lambert | Lambert orbit-transfer solutions |
fleet save | Store a fleet state as a content-addressed snapshot |
fleet list | List stored snapshots |
fleet show | Print a snapshot by identifier |
waveform generate | Generate a modulated IQ capture |
waveform ber | Monte Carlo bit-error-rate sweep |
waveform thresholds | Measure decoder thresholds |
waveform doppler-apply | Apply a pass Doppler profile to a capture |
Invocation
Every example assumes orbitforge is on your PATH. If it is not, either form
works:
cargo run -p orbitforge-cli -- simulate --constellation demo.json
export PATH="$PWD/target/debug:$PATH"The Cargo form rebuilds first if the source has changed.
Flag conventions
| Convention | Detail |
|---|---|
| Naming | lower-kebab-case, with the unit in the name where one applies |
| Units in names | --altitude-km, --frequency-ghz, --duration-hours, --step-seconds |
| Enum values | lower-kebab-case, for example two-body, harris-priester |
| Required flags | Named in the usage line; omitting one is an error, never a silent default |
| Paths | Relative to the working directory |
The CLI and the HTTP API do not share spelling. The CLI writes two-body with a
hyphen; the API field is propagation_model and its value is two_body with an
underscore. See units and
conventions.
Common options
These appear on most analysis commands with consistent meaning and defaults.
| Parameter | Type | Unit | Default | Required | Description |
|---|---|---|---|---|---|
--constellation | path | n/a | — | Yes | Constellation JSON, from `constellation walker`, `import-tle`, `import-ephem`, or `design`. |
--start | string | RFC 3339 UTC | 2026-01-01T00:00:00Z | No | Scenario start epoch. When propagating imported TLEs, use the reference epoch the import reported. |
--duration-hours | float | h | — | No | Analysis window length. The default varies by command: 6 for `simulate`, 24 for `coverage`, 72 for `conjunction screen`. |
--step-seconds | float | s | 60 | No | Fixed time step. Must be well below the shortest event you care about. |
--model | enum | n/a | two-body | No | Propagation model: `two-body`, `j2`, `sgp4`, `numerical`, `ephemeris`. |
--json | path | n/a | — | No | Write the full structured result. Console output is a summary; the JSON is the data. |
Console output is rounded for reading. Exports carry full precision. Quote from the export, not from the terminal, when precision matters.
Output
Most commands print a human-readable summary and optionally write files.
| Flag | Format | Use |
|---|---|---|
--json | JSON | The complete structured result |
--czml | CZML | Time-dynamic scene for the CesiumJS viewer |
--oem | CCSDS OEM (KVN) | Ephemeris interchange with other tools |
--output | Varies | Command-specific primary output |
Not every command accepts every flag. coverage, for instance, prints its
summary and takes no --output. Run a command with --help for its exact set.
Exit behavior
| Condition | Behavior |
|---|---|
| Success | Exit 0, summary on standard output |
| Bad arguments | Non-zero, usage message on standard error, with a suggestion when a flag is close to a real one |
| Runtime failure | Non-zero, Error: followed by a Caused by: chain |
| Model prerequisite unmet | Non-zero, naming the satellite and what it lacks |
Diagnostics name the specific object that failed rather than reporting a generic error:
Error: simulation failed
Caused by:
satellite `demo-s0-p00-sat00` has no TLE; SGP4 propagation requires one (import via TLE)Partial output is not left behind on failure.
Getting help
orbitforge --help # all commands
orbitforge simulate --help # one command, with defaults and value ranges
orbitforge waveform --help # a command group's subcommands--help is authoritative. If this documentation and --help disagree, --help
is right and the page is a defect worth reporting.
main (pre-release)