CastlesDocs
CLI & resultsDocumentation preview

Command and flags

CLI syntax
castles check [--json] [--fixture <case.json>]

The syntax above describes the CLI entrypoint. From a source checkout, run it through corepack pnpm check; the package does not define an installed castles binary.

FlagBehavior
--jsonEmit the bounded castles.preflight.v1 result rather than human-readable text.
--fixture <case.json>Read the complete synthetic binding and response from one fixture. Output is marked fixture.

Statuses

StatusMeaning
readyThe evaluated input is running and matches the profile. Check the evidence before treating it as readiness.
stoppedThe evaluated sandbox matches but is stopped or archived. Castles does not wake it.
unavailableNot configured, not found, unreachable, not settled, or the upstream seam is missing.
incompatibleUnknown profile, unsafe policy, public exposure or missing metadata.
unauthorizedThe owner refused access or its record binds a different sandbox.
reconciliation-requiredStale generation, ambiguous lookup, different returned ID or an unresolved prior attempt.

Read reasons for the specific code and optional field. For example, a configured non-fixture check currently reports upstream_seam_missing. Reason codes are defined in src/preflight.ts.

Exit codes

CodeMeaning
0ready with live-provider evidence. Unreachable with the current CLI.
1Any status other than ready.
2Usage error or unreadable fixture.
3A fixture reported ready. Synthetic input, never readiness.

Nonzero exit codes in the fixture quickstart are intentional. Do not rewrite a fixture result to exit zero to satisfy a readiness gate.

JSON fields

FieldMeaning
schemacastles.preflight.v1.
status / reasonsEvaluation outcome and bounded reason codes.
evidencefixture, live-provider or none. No live client currently exists.
targetProfile, expected generation and redacted owner/sandbox aliases.
sourcePolicyPolicy and exact source pins; these are not observed provider facts.
observedSanitized metadata, or null when unavailable or withheld at the binding boundary.
providerCalls.inspectInspection calls through the supplied client. Fixture-client calls are synthetic, not live provider reads.

Rendered JSON is bounded to 16,384 bytes. Provider text is mapped to fixed vocabularies, bounded forms or null rather than printed directly.

The consumer gate

Readiness condition
result.status === "ready" &&
result.evidence === "live-provider"

The library exposes isLiveReady(result) for this condition. A green fixture test, a source pin, a merged pull request or a ready status alone does not satisfy it.

Search only Coven Castles documentation.