Semantic command results¶
This reference describes the Python semantic CLI in RAES 11.0.2. For a task procedure, use check an artifact.
Contracts and output¶
Each command accepts a path or - for stdin.
SDL uses sdl-yaml/v1 by default. Portable JSON needs its published contract ID.
Human and JSON output use the same typed result.
JSON mode writes one document and a newline to stdout.
The result records the source format, contract, and applicable operation profiles.
The exit statuses are stable for automation:
Exit |
Meaning |
|---|---|
|
The selected operation completed successfully. |
|
Authored or portable input was rejected. |
|
A command, option, or selector was invalid. |
|
The selected operation is not supported for that contract or profile. |
|
A bounded input/output or other expected operational failure occurred. |
|
An unexpected failure was sanitized at the CLI boundary. |
Semantic commands do not fetch remote modules or search pack layouts. They do
not write lockfiles or caches. They do not publish data, call backends, or
manage experiments. resolve reads the RAES declarations and references in an
accepted scenario. env-packs owns module fetch and lockfile workflows.
Operations are available only when the selected contract has an owning semantic
API. SDL supports parse, validate, normalize, resolve, compile, transform, and
inspect. Portable JSON contracts support validate, inspect, and conformance.
Other combinations return exit 3; in particular, the CLI does not describe
portable contract admission as parse-only behavior or SDL validation as a
conformance report.
Existing compatibility surfaces¶
Use raes sdl format --check to check the source format. The old raes sdl resolve, verify-imports, and publish commands maintain module packages.
sdl resolve writes a lockfile. verify-imports checks locked imports.
publish writes an OCI layout.
Publication resolves relative and symlinked entrypoints to one canonical module root. It produces deterministic tar+gzip bytes: identical module bytes produce identical bundle and manifest digests. The completed layout replaces an older layout transactionally, so stale blobs or files are not retained and a failed commit preserves the prior layout.
Signing is explicit. Pass --signer-id and --private-key together to produce
an Ed25519 signature, or omit both for unsigned publication. Supplying only one,
an unreadable/invalid key, or a signer id with surrounding whitespace fails
closed rather than silently publishing unsigned content.
These commands are not part of the offline raes semantic contract. Pack-aware
workflows belong in env-packs. OCI resolution uses bounded configured timeouts.
Its digest-bound extraction cache is committed only after complete validation.
Malformed registry JSON is reported as a stable SDLParseError without
including response bodies or decoder internals.
Use raes processor --help and raes conformance --help for the processor and
backend-contract surfaces.
raes conformance processor runs finite compilation and planning checks.
raes conformance backend --profile provisioning-only checks the published fixtures.
Both commands accept --format text; JSON remains the default.
The report separates requested scope, achieved scope, support gaps, and evidence limits.
Fixture success proves no native backend execution.
The CLI API reference lists the
current command implementation.
Read artifact concepts for the boundary between accepted structure and realized behavior.