orun catalog

orun catalog resolves, persists, and inspects the service catalog — the typed entity model (components plus derived Systems, Domains, Groups, APIs, Resources, Environments, and Compositions, with their relation graph and the impact index) for a workspace at a given source snapshot. It is the content-addressed foundation that powers change detection (--changed), the orun catalog affected query, and the cockpit's live component view. The model itself is described in Service catalog.

orun catalog            # summary of the catalog command group
orun catalog <sub> --help

Subcommands

Subcommand	Purpose
`refresh`	Resolve the current workspace and persist a catalog snapshot
`push`	Sync the resolved snapshot to Orunbase and advance the catalog head
`affected`	Compute the components affected by a change (the change-detection engine)
`list`	List the components in the selected catalog
`describe`	Show the full resolved manifest for one component or entity
`docs`	Print a resolved doc (default: `overview`) carried in the catalog closure
`tree`	Render the catalog relationship graphs
`history`	Enumerate a component's execution history
`diff`	Compare two catalog snapshots
`validate`	Re-resolve in strict mode and report validation issues
`refs`	List every catalog ref with its resolved source/catalog keys
`migrate`	Lint authored `component.yaml` files for `orun.io/v1` readiness (read-only)

A catalog is also written transparently as a side effect of using orun: orun plan and a universal pre-run refresh hook keep catalogs/current fresh, so the read subcommands and the cockpit usually have an up-to-date catalog without an explicit refresh. plan, run, and component --changed also rebuild the snapshot from the working tree whenever the component manifests changed since it was built, and print a one-line notice when that changed the component graph (see Change detection).

`orun catalog refresh`

Resolves the current workspace into a (SourceSnapshot, CatalogSnapshot) pair and persists it, including the impact/ index (the ownership map and per-component fingerprints) used by change detection. A byte-identical re-refresh is idempotent — it reuses the existing snapshot and creates no new directory; a dirty worktree is marked local-only.

orun catalog refresh
orun catalog refresh --json

Flag	Purpose
`--json`	Stable machine-readable output
`--catalog-strict` / `--strict`	Promote validation warnings to errors
`--no-infer`	Disable the inference layer
`--catalog-source` / `--source`	Resolve by ref selector (`current\|main\|latest\|branches/<name>\|prs/<n>\|cat-<key>`)
`--catalog-snapshot`	Bypass refs; pin to an explicit `catalogSnapshotKey`

Exit codes: 0 created or reused · 1 validation error (or any warning under --strict) · 2 resolver internal error · 3 object-store ref conflict.

Flag	Purpose
`--push`	After refreshing, push the snapshot to Orunbase and advance the head
`--environment <name>`	With `--push`: target a named environment head (default: the project-wide head)
`--backend-url <url>`	With `--push`: backend URL (Orunbase or self-hosted)

`orun catalog push`

Syncs the locally resolved catalogs/current snapshot to Orunbase and advances the catalog head, recording the source git commit — which lights up the org-global catalog browser within seconds. It runs in two ordered steps: the object closure is uploaded as a content set-difference (only the blobs the server is missing), then the (project, environment) head is advanced to the snapshot digest. The head advance fails closed if the closure was not uploaded first, and because the model is content-addressed a re-push transfers ~zero bytes.

Run orun catalog refresh first to (re)resolve the workspace; push uploads whatever catalogs/current points at. Scope and credentials resolve the same way as every remote-state call (flag → env → cached link → CI OIDC), so push requires either orun auth login + orun cloud link locally, or the OIDC exchange in CI.

orun catalog push                          # upload the closure + advance the head
orun catalog push --environment staging    # advance a named environment head
orun catalog refresh --push                # refresh then push in one step

Flag	Purpose
`--backend-url <url>`	Backend URL (Orunbase or self-hosted)
`--org <slug>` / `--project <slug>`	Override the cached link scope
`--environment <name>`	Target a named environment head (default: the project-wide head)

`orun catalog affected`

Reads the object-model catalog (its ownership map and dependency graph), classifies the change between --base and --head (or an explicit --files list), and reports the affected component set with a confidence signal. This is the same change-detection engine that orun plan/run --changed and the cockpit use — affected is the way to inspect its output directly.

orun catalog affected
orun catalog affected --base main --head HEAD
orun catalog affected --files apps/api/main.go --json
orun catalog affected --files packages/policy-engine/src/index.ts --explain

The result has four sets:

Field	Meaning
`directlyChanged`	components whose own inputs changed
`dependents`	components that transitively depend on a changed one
`affected`	the cockpit "blast radius" (`directlyChanged` + `dependents`)
`selection`	the plan/run job set (`directlyChanged` + `include:always` deps)

Since v2.22.0, directlyChanged also folds in build-input dependents: components whose dependsOn entries marked input: true point at a changed component (transitively). A worker that bundles a shared package is rescoped — and therefore planned and deployed — when only the package's directory changed. See Dependency rules → Input edges.

directlyChanged also includes components whose spec.change.inputs globs match a changed file — how a root file such as pnpm-lock.yaml or turbo.json, owned by no component, selects the components that build from it.

On classification ambiguity the engine over-reports, never under — a false positive is safe, a missed change is not. A component.yaml edit is treated as structural: it lowers confidence and sets needsFullResolve.

Flag	Purpose
`--base <ref>`	Base ref for change detection (default: `main`)
`--head <ref>`	Head ref for change detection (default: working tree)
`--files <path,...>`	Comma-separated changed files (bypasses git diff)
`--intent-impact <mode>`	How global intent changes affect components (`watch`/`all`/`none`, default `watch`)
`--json`	Emit the `CatalogAffectedResult` JSON envelope
`--explain`	Show why each component was selected (file, intent, or build-input provenance)

The --json envelope (directlyChanged, dependents, affected, selection, confidence, needsFullResolve, intentMode, catalogId) is the provenance-rich projection of the engine's result — use it in CI to explain why a component was (or wasn't) selected.

orun catalog affected exits 6 when no catalog or impact index is present (run orun catalog refresh or orun plan first).

Read subcommands

orun catalog list                 # components in the current catalog
orun catalog list --kind System   # derived entities of another kind
orun catalog describe <name>      # the full v1 envelope for one component or entity
orun catalog docs <entity> [doc]  # a resolved doc from the catalog closure (default: overview)
orun catalog tree                 # the catalog relationship graphs
orun catalog history <name>       # a component's execution history
orun catalog diff [component]     # compare two catalog snapshots (--base, default main; --head, default current)
orun catalog refs                 # every catalog ref + resolved source/catalog keys

These read whatever has been persisted (most recently catalogs/current); they never resolve unless you ask for refresh.

`orun catalog list`

Prints one row per component — key, type, owner, system, and last execution status. Owners are typed refs (group:<name>, user:<name>), resolved from authored manifests or CODEOWNERS.

Flag	Purpose
`--kind <Kind>`	List derived entities of a kind (`API\|Resource\|System\|Domain\|Group\|Environment\|Composition`) instead of components; derived entities show a MEMBERS count
`--owner` / `--system` / `--domain` / `--type` / `--status`	Narrow the component set
`--json`	Stable machine-readable output

`orun catalog describe`

Renders the full orun.io/v1 envelope for one entity: identity and lifecycle, ownership (with its provenance), environments, dependencies, APIs, resources, integrations, vendor extensions, inferred runtime, live deployments, latest executions, and resolution provenance. The argument may be a bare name or a fully-qualified namespace/repo/name key; an ambiguous bare name exits 4 with the candidate keys.

`orun catalog validate`

Re-resolves the workspace and prints the validation issues without persisting anything. Any error exits 1; warnings exit 0 unless --strict promotes them. --json emits the CatalogValidateResult envelope.

orun catalog validate
orun catalog validate --strict --json

One ref names one entity. A Domain, System, Environment, API, Resource, Composition, Repo, or agent type whose name resolves to the same <namespace>/<repo>/<name> ref as a component is an error (catalog.entity.ref.collision). The kind is not part of the ref, so spec.domain: web on the web component gives both the same ref, and Orunbase keeps only one of them. The issue points at the declaration to rename and names both entities:

error   catalog.entity.ref.collision     apps/web/component.yaml#/spec/domain — catalog ref default/shop/web names 2 entities of different kinds: Component "web" (apps/web/component.yaml) and Domain "web" (spec.domain in apps/web/component.yaml). A ref names one entity, so the catalog keeps the Component and leaves the Domain out. Rename one of them — e.g. the Domain's spec.domain in apps/web/component.yaml

orun plan and orun catalog refresh do not fail on it. They print the same line as a warning: catalog: and write the catalog with the Component, leaving the other entity out.

`orun catalog migrate`

Read-only, advisory lint of the workspace's authored component.yaml files for orun.io/v1 readiness. Reports, per component, the gaps that keep it from being a first-class v1 entity — a legacy apiVersion, a missing owner (none authored and no CODEOWNERS match), a missing lifecycle stage, a missing system — plus a summary count of ready components. It never rewrites files; v1 authoring is additive and un-migrated components still resolve.

orun catalog migrate          # per-file findings + ready count
orun catalog migrate --json   # the CatalogMigrateResult envelope, for CI

Subcommands​

orun catalog refresh​

orun catalog push​

orun catalog affected​

Read subcommands​

orun catalog list​

orun catalog describe​

orun catalog validate​

orun catalog migrate​

See also​