CLI Contract v1¶

Status: Active v1.0 contract
Scope: CLI compatibility classification for documented workflows
Applies to: OrbitFabric CLI from v1.0.0 - Stable Mission Data Contract onward

This page classifies the current OrbitFabric CLI surface after v1.0.0.

It is a documentation contract. It does not introduce new commands, new options, new behavior, new Mission Model semantics, new reports, plugin execution, runtime behavior, ground behavior or Studio-specific APIs.

1. Purpose¶

The OrbitFabric CLI is a public user-facing workflow surface.

From v1.0.0 onward, documented command names, command groups, required arguments, documented options and documented machine-readable outputs for selected workflows are compatibility-sensitive.

This page identifies the current CLI surface and separates:

command names;
command groups;
required arguments;
documented options;
human-oriented output;
machine-readable output paths and report families;
unsupported compatibility assumptions.

2. Stability classification¶

Current CLI classification:

CLI area	Classification	Notes
top-level command name `orbitfabric`	Stable contract	User-facing entry point.
top-level command groups	Stable contract	`gen`, `validate`, `inspect`, `export`.
top-level commands	Stable contract	`lint`, `sim`.
documented options	Stable contract	Option names are compatibility-sensitive after v1.0.0.
command required arguments	Stable contract	Required positional arguments are compatibility-sensitive.
CLI textual output	Human-oriented public preview	Useful for users. Not a machine contract.
JSON outputs produced via `--json`	Stable report surface where documented	Machine-readable report families are documented separately.
generated artifact paths	Public preview or stable depending on surface	Paths are compatibility-sensitive when documented.
internal Python implementation	Internal implementation detail	Not a CLI contract.

3. Top-level CLI surface¶

Current top-level invocation:

orbitfabric --help
orbitfabric --version

Current top-level commands and groups:

orbitfabric lint
orbitfabric sim
orbitfabric gen ...
orbitfabric validate ...
orbitfabric inspect ...
orbitfabric export ...

orbitfabric --version reports the OrbitFabric tool/package version.

The OrbitFabric tool/package version is not the same thing as the Mission Model version declared by a mission.

4. Lint command¶

Current command:

orbitfabric lint <mission_dir>

Current documented options:

--json <path>
--warnings-as-errors

Compatibility-sensitive behavior:

the command validates and semantically lints a Mission Model directory;
the required argument is a readable mission directory;
--json writes a machine-readable lint report;
--warnings-as-errors makes warning-level findings fail the command.

Human-oriented terminal text is not a machine contract.

The lint JSON report structure is documented separately in JSON Reports v0.1.

5. Simulation command¶

Current command:

orbitfabric sim <scenario_file>

Current documented options:

--json <path>
--log <path>

Compatibility-sensitive behavior:

the command executes a scenario YAML file against its referenced Mission Model;
the required argument is a readable scenario file;
--json writes a machine-readable simulation report;
--log writes a plain-text simulation timeline log.

The JSON simulation report is a machine-readable stable surface.

The plain-text log is human-reviewable evidence and should not be treated as a machine contract.

6. Generation command group¶

Current command group:

orbitfabric gen ...

Current generation commands:

orbitfabric gen docs
orbitfabric gen data-flow
orbitfabric gen runtime
orbitfabric gen ground

These commands generate artifacts derived from the validated Mission Model.

Generated artifacts are disposable outputs unless explicitly classified otherwise. They must not become the source of truth.

7. Documentation generation¶

Current command:

orbitfabric gen docs <mission_dir>

Current documented option:

--output-dir <path>

Default output directory:

generated/docs

Compatibility-sensitive behavior:

generates Markdown documentation from the Mission Model;
aborts when lint errors exist;
writes human-reviewable generated documentation.

Generated Markdown documentation is not the Mission Data Contract source of truth.

8. Data-flow documentation generation¶

Current command:

orbitfabric gen data-flow <mission_dir>

Current documented option:

--output-file <path>

Default output file:

generated/docs/data_flow.md

Compatibility-sensitive behavior:

generates Markdown data-flow documentation from the Mission Model;
aborts when lint errors exist;
writes a human-reviewable data-flow documentation artifact.

9. Runtime-facing generation¶

Current command:

orbitfabric gen runtime <mission_dir>

Current documented options:

--output-dir <path>
--profile <profile>

Current default output directory:

generated/runtime

Current supported profile:

cpp17

Compatibility-sensitive behavior:

generates runtime-facing contract artifacts from the Mission Model;
aborts when lint errors exist;
rejects unsupported runtime generation profiles;
writes a runtime contract manifest and generated C++17 binding artifacts.

This command does not generate flight software, scheduler behavior, command dispatch runtime, telemetry polling runtime, drivers, RTOS integration or protected user-code regions.

10. Ground-facing generation¶

Current command:

orbitfabric gen ground <mission_dir>

Current documented options:

--output-dir <path>
--profile <profile>

Current default output directory:

generated/ground

Current supported profile:

generic

Compatibility-sensitive behavior:

generates ground-facing contract artifacts from the Mission Model;
aborts when lint errors exist;
rejects unsupported ground generation profiles;
writes a ground contract manifest, JSON dictionaries, CSV dictionaries and human-reviewable Markdown artifacts.

This command does not generate a live ground segment, database, command uplink service, operator console, telemetry archive, transport layer or station automation.

11. Export command group¶

Current command group:

orbitfabric export ...

Current export commands:

orbitfabric export model-summary
orbitfabric export entity-index
orbitfabric export relationship-manifest

These commands export Core-owned read-only machine-readable inspection surfaces.

They are the supported downstream inspection boundary.

Downstream tools must consume these surfaces instead of reconstructing Mission Data Contract semantics from raw YAML, generated artifacts, textual CLI output or UI state.

12. Model summary export¶

Current command:

orbitfabric export model-summary <mission_dir>

Current documented option:

--json <path>

Default output file:

generated/reports/model_summary.json

Compatibility-sensitive behavior:

exports the Core-owned model summary surface;
answers what contract domains are present;
writes a machine-readable JSON report.

13. Entity index export¶

Current command:

orbitfabric export entity-index <mission_dir>

Current documented option:

--json <path>

Default output file:

generated/reports/entity_index.json

Compatibility-sensitive behavior:

exports the Core-owned entity index surface;
answers what contract entities are defined;
writes a machine-readable JSON report.

14. Relationship manifest export¶

Current command:

orbitfabric export relationship-manifest <mission_dir>

Current documented option:

--json <path>

Default output file:

generated/reports/relationship_manifest.json

Compatibility-sensitive behavior:

exports the stable Core-owned relationship manifest surface for admitted families;
answers how indexed mission contract entities are related;
writes a machine-readable JSON report.

This command does not expose a relationship graph, dependency graph, plugin API, runtime routing table, ground routing table or Studio-specific API.

15. Inspect command group¶

Current command group:

orbitfabric inspect ...

Current inspect command:

orbitfabric inspect mission

Current command:

orbitfabric inspect mission <mission_dir>

Compatibility-sensitive behavior:

loads and inspects a Mission Model directory;
prints a human-oriented loaded model summary;
does not lint, generate artifacts or export machine-readable reports.

The terminal output is human-oriented and must not be treated as a machine contract.

16. Validate command group¶

Current command group:

orbitfabric validate ...

Current validate command:

orbitfabric validate scenario

Current command:

orbitfabric validate scenario <scenario_file>

Compatibility-sensitive behavior:

validates a scenario YAML file without executing it;
loads the referenced Mission Model;
reports human-oriented scenario summary information.

This command does not execute scenario behavior, generate evidence reports or mutate Mission Model data.

17. Machine-readable versus human-oriented output¶

Only explicitly documented JSON reports and Core-owned structured surfaces should be treated as machine-readable stable or public preview outputs.

Human-oriented terminal output is useful for users, demonstrations and diagnostics, but it is not a machine compatibility contract.

Scripts and downstream tools should prefer:

--json outputs
model_summary.json
entity_index.json
relationship_manifest.json
generated manifests

over parsing terminal text.

18. Compatibility-sensitive CLI changes¶

The following changes are compatibility-sensitive after v1.0.0:

renaming a documented command;
removing a documented command;
moving a documented command to another group;
renaming a documented option;
removing a documented option;
changing a required positional argument;
changing the default output path of a documented generated artifact;
changing supported profile names;
changing documented command failure behavior;
changing the machine-readable report family produced by a command.

Compatibility-sensitive does not mean forbidden.

It means the change must be explicit, reviewed and documented.

19. Current CLI non-goals¶

The CLI contract does not introduce or promise:

shell completion compatibility
terminal text parsing compatibility
plugin command discovery
plugin command execution
remote execution
background jobs
watch mode
live mission operations
flight runtime behavior
ground runtime behavior
operator console behavior
Studio-specific API behavior

20. Final statement¶

v1.0.0 stabilizes documented CLI workflows enough for users and CI workflows to rely on command names, command groups, required arguments, documented options and machine-readable outputs, without freezing human-oriented terminal prose.