Skip to content

cli.md

Latest commit

 

History

History
1438 lines (946 loc) · 54.6 KB

cli.md

File metadata and controls

1438 lines (946 loc) · 54.6 KB
Raw

CLI reference

Every ost command. Every command also accepts the global --json flag (a versioned {ok, schema, data, warnings} envelope; see json-output.md).

ost

OpenStrata command-line interface (the ost binary).

Usage: ost [OPTIONS] <COMMAND>

Options:

Option Description
--json Emit machine-readable JSON instead of human-formatted output
--redact-paths Replace local filesystem and managed-environment values in JSON with stable placeholders suitable for attaching to a public report

Subcommands:

  • ost artifact — Import, inspect, verify, export, and pull artifacts (local registry + remote OCI transport)
  • ost build — Configure and build a target with CMake + Ninja
  • ost ci — Manage the CI support matrix and generate CI configuration
  • ost configure — Generate CMake toolchain and presets for a target
  • ost devshell — Enter an interactive shell with a runtime activated
  • ost doctor — Diagnose host, tools, and (optionally) a runtime
  • ost env — Print the environment that activates a runtime (for eval)
  • ost extension — Inspect and request controlled extensions
  • ost external — Import and inspect provenance for a build OpenStrata did not perform
  • ost formation — Resolve, inspect, diagnose, export, lock, and run digest-pinned Formations
  • ost host — Discover, list, and inspect third-party DCC hosts (Maya, Houdini)
  • ost init — Initialise an OpenStrata project in the current directory
  • ost lock — Generate or verify the project lockfile (strata.lock)
  • ost package — Install and pack a built target into a tar.zst artifact
  • ost platform — Inspect VFX Reference Platform calendar-year definitions
  • ost plugin — Scaffold, inspect, build, and diagnose OpenUSD plugin bundles
  • ost presets — Manage OpenStrata's CMake preset includes in CMakePresets.json
  • ost renderer — Inspect renderer projects in host applications
  • ost runtime — Pull, list, and inspect runtimes in the local store
  • ost test — Run a built target's tests under the runtime that built it
  • ost uv — Run uv pinned to the project's runtime Python
  • ost validate — Validate a built/packaged target

ost artifact

Import, inspect, verify, export, and pull artifacts (local registry + remote OCI transport)

Usage: ost artifact <COMMAND>

Subcommands:

ost artifact export

Export an artifact's files into a directory (CI handoff)

Usage: ost artifact export <DIGEST> <DEST>

Arguments:

Argument Required Description
<DIGEST> yes Digest reference: sha256: or a unique hex prefix (>= 6 chars)
<DEST> yes Destination directory (created if missing; files must not exist)

ost artifact extract

Unpack an artifact's archive into a directory (digest re-verified)

Usage: ost artifact extract [OPTIONS] <DIGEST> [<DEST>]

Arguments:

Argument Required Description
<DIGEST> yes Digest reference: sha256: or a unique hex prefix (>= 6 chars)
<DEST> no Destination directory (created if missing). May also be given as --into <DEST>

Options:

Option Description
--into <INTO> Named form of the destination directory, e.g. ost artifact extract <digest> --into ./out

ost artifact import

Import a package output into the local registry, keyed by digest

Usage: ost artifact import <PATH>

Arguments:

Argument Required Description
<PATH> yes A dist directory containing manifest.json (+ archive), or the manifest.json itself

ost artifact list

List artifacts in the local registry

Usage: ost artifact list [OPTIONS]

Options:

Option Description
--kind <KIND> Only show artifacts of this kind: runtime | plugin | product | package

ost artifact pull

Pull a digest-pinned artifact from a remote source, verify it, and import it into the local registry

Usage: ost artifact pull [OPTIONS] <REFERENCE>

Arguments:

Argument Required Description
<REFERENCE> yes oci://…@sha256: or file://. Mutable (tag-only) references are refused: resolve them first

Options:

Option Description
--expect-artifact <sha256:<hex>> Require the pulled OpenStrata artifact digest to equal this pin (the support line / lockfile contract)
--plain-http Use plain http:// instead of https:// (fixture registries and air-gapped mirrors only)
--require-kind <KIND> Require the artifact kind: runtime | plugin | product | package
--require-target <TARGET> Require the artifact's target id to match exactly

ost artifact push

Push a stored artifact to a remote OCI registry (the producer verb)

Usage: ost artifact push [OPTIONS] <DIGEST> <DESTINATION>

Arguments:

Argument Required Description
<DIGEST> yes Digest reference of a stored artifact: sha256: or a unique hex prefix (>= 6 chars)
<DESTINATION> yes Destination: oci:///[:tag][@sha256:]. A pinned digest is verified against the computed manifest digest

Options:

Option Description
--allow-untrusted-publisher Explicitly bypass publisher identity checks for a protected namespace. The override is recorded in command output
--plain-http Use plain http:// instead of https:// (fixture registries and air-gapped mirrors only)
--policy <FILE> Artifact policy TOML. When omitted, search the current directory and its parents for openstrata-artifact-policy.toml

ost artifact resolve

Resolve a remote reference (tag) to its immutable digest

Usage: ost artifact resolve [OPTIONS] <REFERENCE>

Arguments:

Argument Required Description
<REFERENCE> yes oci:///[:tag][@sha256:]

Options:

Option Description
--plain-http Use plain http:// instead of https:// (fixture registries and air-gapped mirrors only)

ost artifact rm

Remove an artifact from the local registry so it can be re-imported

Usage: ost artifact rm <DIGEST>

Arguments:

Argument Required Description
<DIGEST> yes Digest reference: sha256: or a unique hex prefix (>= 6 chars)

ost artifact show

Show the full identity record for one artifact

Usage: ost artifact show <DIGEST>

Arguments:

Argument Required Description
<DIGEST> yes Digest reference: sha256: or a unique hex prefix (>= 6 chars)

ost artifact verify

Verify a stored artifact's integrity (archive digest + per-file hashes)

Usage: ost artifact verify [OPTIONS] <DIGEST>

Arguments:

Argument Required Description
<DIGEST> yes Digest reference: sha256: or a unique hex prefix (>= 6 chars)

Options:

Option Description
--minimum-trust <LEVEL> Enforce an explicit trust floor. When --policy is also present, the stricter of this value and the policy's minimum is used
--policy <FILE> Enforce minimum trust from an artifact policy TOML file
--require-provenance Fail unless valid SLSA/in-toto provenance is attached
--require-sbom Fail unless a valid SPDX SBOM is attached to the artifact

ost build

Configure and build a target with CMake + Ninja

Usage: ost build [OPTIONS]

Options:

Option Description
--build-timeout <BUILD_TIMEOUT> Build timeout in seconds; 0 disables it
--busy-timeout <BUSY_TIMEOUT> How long --on-busy wait waits, in seconds; 0 waits indefinitely
--cc <CC> C compiler path (implies --compiler explicit)
--check Run preflight checks only, without generating files or building
--compiler <COMPILER> Compiler policy: host (default), runtime, or explicit
--config <CONFIG> Build configuration (CMAKE_BUILD_TYPE and multi-config --config)
--configure-timeout <CONFIGURE_TIMEOUT> Configure timeout in seconds; 0 disables it
--cxx <CXX> C++ compiler path (implies --compiler explicit)
--dry-run Print the commands and files that would be produced, without executing or writing anything
--generator <GENERATOR> CMake generator. Ninja remains the default
--intent <INTENT> Project-declared build intent from [build.intents.]
--jobs <JOBS> Parallel jobs: a number, or auto to let Ninja decide
--ninja <NINJA> Path to the ninja executable if it is not on PATH
--no-vcvars Do not auto-load the MSVC developer environment (Windows)
--notify Fire a desktop notification when the build finishes (no-op over SSH/CI)
--on-busy <ON_BUSY> What to do when another invocation is already writing this target: fail immediately, wait for it (see --busy-timeout), or read-only to proceed without taking the target lease
--profile <PROFILE> Profile to build. Defaults to the project's profile
--progress <PROGRESS> Progress rendering: auto (human on a TTY, plain otherwise), plain, or json (one JSON event per line)
--quiet Suppress progress output; child output goes to the log. Failures, the exit code and the log path are still reported
--target <TARGET> Platform target, e.g. cy2026. Defaults to the project's platform

ost ci

Manage the CI support matrix and generate CI configuration

Usage: ost ci <COMMAND>

Subcommands:

  • ost ci generate — Generate CI configuration from the support matrix
  • ost ci init — Write a starter openstrata.ci.yaml support matrix
  • ost ci matrix — Emit the resolved cells so a workflow ost ci generate cannot express can consume the same pins instead of copying them
  • ost ci plan — Report preflight execution facts (lanes, runners, billing)
  • ost ci validate — Validate the support matrix

ost ci generate

Generate CI configuration from the support matrix

Usage: ost ci generate <COMMAND>

Subcommands:

ost ci generate github

Emit a GitHub Actions workflow (one job per support cell)

Usage: ost ci generate github [OPTIONS]

Options:

Option Description
--allow-placeholders Render even if cells still carry the scaffold's all-zero placeholder digests
--force Overwrite an existing workflow file
--matrix <MATRIX> Path to the matrix file. Defaults to ./openstrata.ci.yaml
--out <OUT> Output path. Defaults to .github/workflows/ost-support-matrix.yml
--stdout Print the workflow to stdout instead of writing a file
--support <SUPPORT> Refuse generation when hosted claims exceed this support declaration

ost ci init

Write a starter openstrata.ci.yaml support matrix

Usage: ost ci init [OPTIONS]

Options:

Option Description
--dir <DIR> Directory to write into. Defaults to the current directory

ost ci matrix

Emit the resolved cells so a workflow ost ci generate cannot express can consume the same pins instead of copying them

Usage: ost ci matrix [OPTIONS]

Options:

Option Description
--lane <LANE> Only cells in this lane (pull_request | main | scheduled | workflow_dispatch). All lanes when omitted
--matrix <MATRIX> Path to the matrix file. Defaults to ./openstrata.ci.yaml

ost ci plan

Report preflight execution facts (lanes, runners, billing)

Usage: ost ci plan [OPTIONS]

Options:

Option Description
--matrix <MATRIX> Path to the matrix file. Defaults to ./openstrata.ci.yaml

ost ci validate

Validate the support matrix

Usage: ost ci validate [OPTIONS]

Options:

Option Description
--matrix <MATRIX> Path to the matrix file. Defaults to ./openstrata.ci.yaml
--resolve Also require every pinned digest to resolve in the local registry
--support <SUPPORT> Check hosted cells against a public support/platform declaration

ost configure

Generate CMake toolchain and presets for a target

Usage: ost configure [OPTIONS]

Options:

Option Description
--busy-timeout <BUSY_TIMEOUT> How long --on-busy wait waits, in seconds; 0 waits indefinitely
--cc <CC> C compiler path (implies --compiler explicit)
--compiler <COMPILER> Compiler policy: host (default), runtime, or explicit
--cxx <CXX> C++ compiler path (implies --compiler explicit)
--on-busy <ON_BUSY> What to do when another invocation is already writing this target: fail immediately, wait for it (see --busy-timeout), or read-only to proceed without taking the target lease
--profile <PROFILE> Profile to build. Defaults to the project's profile
--target <TARGET> Platform target, e.g. cy2026. Defaults to the project's platform

ost devshell

Enter an interactive shell with a runtime activated

Usage: ost devshell [OPTIONS] <PLATFORM>

Arguments:

Argument Required Description
<PLATFORM> yes Platform calendar-year id, e.g. cy2026

Options:

Option Description
--profile <PROFILE> Profile to activate, e.g. usd or lookdev
--shell <SHELL> Shell to launch. Defaults to the host's conventional shell

ost doctor

Diagnose host, tools, and (optionally) a runtime

Usage: ost doctor [OPTIONS] [<PLATFORM>]

Arguments:

Argument Required Description
<PLATFORM> no Optional platform to diagnose a specific runtime, e.g. cy2026

Options:

Option Description
--capability <CAPABILITIES> The capability you intend to exercise, e.g. usd-stage-read. Advice is scoped to it: without an OpenUSD-dependent capability — in the profile or named here — doctor does not tell you to go and find a real OpenUSD
--profile <PROFILE> Profile to diagnose (only with a platform)

ost env

Print the environment that activates a runtime (for eval)

Usage: ost env [OPTIONS] <PLATFORM>

Arguments:

Argument Required Description
<PLATFORM> yes Platform calendar-year id, e.g. cy2026

Options:

Option Description
--profile <PROFILE> Profile to activate, e.g. usd or lookdev
--shell <SHELL> Target shell. Defaults to the host's conventional shell

ost extension

Inspect and request controlled extensions

Usage: ost extension <COMMAND>

Subcommands:

ost extension add

Add an extension to the project manifest

Usage: ost extension add <NAME>

Arguments:

Argument Required Description
<NAME> yes Extension id, e.g. materialx

ost extension list

List the known extensions

Usage: ost extension list

ost extension why

Explain why an extension is required by a profile

Usage: ost extension why [OPTIONS] <NAME>

Arguments:

Argument Required Description
<NAME> yes Extension id, e.g. materialx

Options:

Option Description
--profile <PROFILE> Profile to trace. Defaults to the project's profile

ost external

Import and inspect provenance for a build OpenStrata did not perform

Usage: ost external <COMMAND>

Subcommands:

ost external import

Inspect an external build tree's CMake cache and record its provenance

Usage: ost external import [OPTIONS]

Options:

Option Description
--build-dir <BUILD_DIR> The external build tree to inspect
--capability <CAPABILITIES> Additional capability this external tree is intended to exercise. May be repeated; requirements are combined with the resolved profile
--config <CONFIG> Configuration whose binaries the import describes. Required for multi-config generators such as Visual Studio and Ninja Multi-Config
--profile <PROFILE> Profile. Defaults to the project's profile
--target <TARGET> Platform target, e.g. cy2026. Defaults to the project's platform

ost external show

Show the provenance recorded for an external build tree

Usage: ost external show [OPTIONS]

Options:

Option Description
--build-dir <BUILD_DIR> The external build tree whose record should be shown

ost formation

Resolve, inspect, diagnose, export, lock, and run digest-pinned Formations

Usage: ost formation <COMMAND>

Subcommands:

ost formation doctor

Diagnose resolution, lock state, environment, and command reachability

Usage: ost formation doctor [<PATH>]

Arguments:

Argument Required Description
<PATH> no Formation manifest to resolve

ost formation env

Print the fully composed Formation environment

Usage: ost formation env [OPTIONS] [<PATH>]

Arguments:

Argument Required Description
<PATH> no Formation manifest to resolve

Options:

Option Description
--shell <SHELL> Target shell. Defaults to the host's conventional shell

ost formation inspect

Inspect the current resolution and any adjacent lock state

Usage: ost formation inspect [<PATH>]

Arguments:

Argument Required Description
<PATH> no Formation manifest to resolve

ost formation lock

Write a deterministic, digest-pinned formation.lock

Usage: ost formation lock [OPTIONS] [<PATH>]

Arguments:

Argument Required Description
<PATH> no Formation manifest to lock

Options:

Option Description
--output <OUTPUT> Lock path (defaults to formation.lock beside the manifest)

ost formation resolve

Resolve immutable artifacts, compatibility, and environment without launching

Usage: ost formation resolve [<PATH>]

Arguments:

Argument Required Description
<PATH> no Formation manifest to resolve

ost formation run

Launch the Formation's command in the foreground and record evidence

Usage: ost formation run [<PATH>] [<COMMAND>]

Arguments:

Argument Required Description
<PATH> no Formation manifest to run
<COMMAND> no Override [command] with a program and arguments after --

ost host

Discover, list, and inspect third-party DCC hosts (Maya, Houdini)

Usage: ost host <COMMAND>

Subcommands:

ost host discover

Scan for DCC installs and record what was found

Usage: ost host discover [OPTIONS]

Options:

Option Description
--depth <DEPTH> How deep below each scanned root an install may sit
--fingerprint <FINGERPRINT> Fingerprint depth: standard (identity and layout) or deep (also hashes the selected executables)
--from-path Also accept install roots derived from executables on PATH. Off by default: PATH reflects the calling shell, not the machine
--host <FAMILY> Restrict discovery to one family (maya, houdini). Repeatable
--no-environment Skip the vendor environment variables (MAYA_LOCATION, HFS)
--no-known-roots Skip this platform's documented default install locations
--path <PATH> Validate this exact install root. Repeatable. A path that is not a host is reported with the reason, rather than silently skipped
--probe Run each host's own --version when shipped metadata cannot answer. Executes the host binary under a bounded timeout
--refresh Ignore the cached inventory and rescan. Discovery always rescans; this additionally discards records the scan did not re-find
--register Also write the result to the project's reviewable .strata/hosts/ inventory
--root <PATH> Scan this directory in addition to [host.discovery].roots. Repeatable

ost host inspect

Show one host record in full

Usage: ost host inspect <SELECTOR>

Arguments:

Argument Required Description
<SELECTOR> yes Instance id, install path, family name, or id prefix — the last three only when they name exactly one install

ost host list

List the hosts already recorded, re-checked against the filesystem

Usage: ost host list [OPTIONS]

Options:

Option Description
--host <FAMILY> Restrict the listing to one family
--status <STATUS> Restrict the listing to one status

ost init

Initialise an OpenStrata project in the current directory

Usage: ost init [OPTIONS]

Options:

Option Description
--bare Write only the manifest (no CMake files) — for an existing CMake project
--force Overwrite an existing manifest and template files if present
--name <NAME> Project name. Defaults to the current directory name
--platform <PLATFORM> Platform calendar-year to target, e.g. cy2026. Defaults to the latest
--template <TEMPLATE> Project template: cpp-library (default), renderer, usd-plugin, or usd-plugin-workspace (dual-mode root for ost plugin new bundles)

ost lock

Generate or verify the project lockfile (strata.lock)

Usage: ost lock [OPTIONS]

Options:

Option Description
--check Verify the on-disk lock is up to date instead of writing it (exit 1 if not)
--profile <PROFILE> Profile to lock. Defaults to the project's profile
--target <TARGET> Platform target, e.g. cy2026. Defaults to the project's platform

ost package

Install and pack a built target into a tar.zst artifact

Usage: ost package [OPTIONS]

Options:

Option Description
--allow-empty Allow an empty install tree (a metadata-only artifact). By default an empty tree is an error
--clean-stage Reclaim the stable package stage harder and sweep stale fallback stages a previous locked run left behind, instead of quietly staging into yet another sibling. Use once the process holding the old stage has exited
--profile <PROFILE> Profile to package. Defaults to the project's profile
--target <TARGET> Platform target, e.g. cy2026. Defaults to the project's platform

ost platform

Inspect VFX Reference Platform calendar-year definitions

Usage: ost platform <COMMAND>

Subcommands:

ost platform diff

Show component differences between two platform years

Usage: ost platform diff <FROM> <TO>

Arguments:

Argument Required Description
<FROM> yes Older platform id, e.g. cy2025
<TO> yes Newer platform id, e.g. cy2026

ost platform list

List all known platform definitions

Usage: ost platform list

ost platform show

Show the full definition of one platform year

Usage: ost platform show <ID>

Arguments:

Argument Required Description
<ID> yes Platform id, e.g. cy2026

ost plugin

Scaffold, inspect, build, and diagnose OpenUSD plugin bundles

Usage: ost plugin <COMMAND>

Subcommands:

ost plugin build

Build the plugin's shared library against the resolved runtime

Usage: ost plugin build [OPTIONS] <BUNDLE>

Arguments:

Argument Required Description
<BUNDLE> yes Path to the bundle directory

Options:

Option Description
--cc <CC> C compiler path (implies --compiler explicit)
--compiler <COMPILER> Compiler policy: host (default), runtime, or explicit
--cxx <CXX> C++ compiler path (implies --compiler explicit)
--dry-run Print the commands that would run, without executing them
--ninja <NINJA> Path to the ninja executable if it is not on PATH
--profile <PROFILE> Profile to build against. Defaults to the enclosing project's
--target <TARGET> Platform target, e.g. cy2026. Defaults to the enclosing project's

ost plugin doctor

Run staged diagnostics (L0–L1) and write a report

Usage: ost plugin doctor [OPTIONS] <BUNDLE>

Arguments:

Argument Required Description
<BUNDLE> yes Path to the bundle directory

Options:

Option Description
--profile <PROFILE> Profile to check against. Defaults to the enclosing project's
--target <TARGET> Platform target, e.g. cy2026. Defaults to the enclosing project's
--with <WITH> Additional plugin bundle(s) to include in the session env

ost plugin inspect

Report a bundle's Level 0 structure

Usage: ost plugin inspect [OPTIONS] <BUNDLE>

Arguments:

Argument Required Description
<BUNDLE> yes Path to the bundle directory (containing openstrata.plugin.yaml)

Options:

Option Description
--expect-version <EXPECT_VERSION> Fail unless the manifest declares exactly this plugin version (generated release gates pin the tag's version here)

ost plugin new

Scaffold a new plugin bundle from a template

Usage: ost plugin new [OPTIONS] <KIND> <NAME>

Arguments:

Argument Required Description
<KIND> yes Plugin kind: usd-fileformat | usd-asset-resolver | usd-package-resolver | usd-exec | usd-schema
<NAME> yes Plugin name (becomes the bundle directory), e.g. toy

Options:

Option Description
--dir <DIR> Destination directory. Defaults to ./
--extension <EXTENSION> File extension the plugin handles (required for usd-fileformat and usd-package-resolver)
--schema-bundle <SCHEMA_BUNDLE> Public schema bundle whose contract the OpenExec plugin consumes (required for usd-exec)
--schema-type <SCHEMA_TYPE> C++ schema type used by EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA (required for usd-exec), e.g. VrmSchemaContractAPI
--scheme <SCHEME> URI scheme the resolver handles (required for usd-asset-resolver)
--template <TEMPLATE> Catalog template id. usd-schema defaults to usd-schema-codeless; use usd-schema-cpp for the experimental compiled skeleton

ost plugin package

Pack a built plugin bundle into a target-specific tar.zst artifact

Usage: ost plugin package [OPTIONS] [<BUNDLE>]

Arguments:

Argument Required Description
<BUNDLE> no Path to the bundle directory (omit with --workspace)

Options:

Option Description
--allow-unmanaged-output Package outputs that no longer match the last ost plugin build, recording the package origin as an explicit unmanaged override. Without this flag, a managed-output mismatch fails closed
--clean-stage Reclaim the stable package stage harder and sweep stale fallback stages a previous locked run left behind, instead of quietly staging into another sibling. Use once the holding process has exited
--product Also emit one aggregate product artifact containing the exact member archives, manifests, checksums and evidence in dependency order. Requires --workspace
--profile <PROFILE> Profile to package against. Defaults to the enclosing project's
--target <TARGET> Platform target, e.g. cy2026. Defaults to the enclosing project's
--with-debug Ship debug symbols (.pdb, .dwo) inside the main package instead of the default lean package. By default the main archive is lean and any debug symbols are split into a sibling *-debug package
--workspace Package every discovered bundle, in dependency order, using the same validated graph plugin test --workspace checks

ost plugin product

Verify or install an aggregate plugin product artifact

Usage: ost plugin product <COMMAND>

Subcommands:

ost plugin product install

Verify and install every member in dependency order

Usage: ost plugin product install [OPTIONS] <PRODUCT>

Arguments:

Argument Required Description
<PRODUCT> yes Product dist directory, manifest.json, or product .tar.zst archive

Options:

Option Description
--expect-digest <EXPECT_DIGEST> Require the outer product archive to have this full sha256 digest
--prefix <PREFIX> New installation root. The command refuses to overwrite it
ost plugin product verify

Verify the product archive and every member archive/checksum

Usage: ost plugin product verify [OPTIONS] <PRODUCT>

Arguments:

Argument Required Description
<PRODUCT> yes Product dist directory, manifest.json, or product .tar.zst archive

Options:

Option Description
--expect-digest <EXPECT_DIGEST> Require the outer product archive to have this full sha256 digest

ost plugin publish

Publish a packaged plugin artifact into the local registry (by digest)

Usage: ost plugin publish [OPTIONS] <BUNDLE>

Arguments:

Argument Required Description
<BUNDLE> yes Path to the bundle directory

Options:

Option Description
--profile <PROFILE> Profile the package was built against. Defaults to the project's
--target <TARGET> Platform target, e.g. cy2026. Defaults to the enclosing project's

ost plugin run

Launch a command inside the plugin's runtime session (needs a real runtime)

Usage: ost plugin run [OPTIONS] <BUNDLE> <COMMAND>

Arguments:

Argument Required Description
<BUNDLE> yes Path to the bundle directory
<COMMAND> yes Command to execute after --, e.g. -- usdcat fixture.toy

Options:

Option Description
--no-inject Do not inject the source bundle's own build-tree plugInfo/lib/python paths. The session becomes the bare runtime env plus any --plugin-path / --with trees — an ost runtime run-style USD-only session. The bundle argument then only selects the runtime
--plugin-path <PLUGIN_PATH> External installed/extracted plugin tree(s) to put on the discovery path — an extracted package root (holds openstrata.plugin.yaml), not the source bundle. Use with --no-inject to run a clean-install / discovery test against the shipped layout rather than the build tree
--profile <PROFILE> Profile to activate. Defaults to the enclosing project's
--target <TARGET> Platform target, e.g. cy2026. Defaults to the enclosing project's
--with <WITH> Additional plugin bundle(s) to include in the session env

ost plugin schema

Manage a bundle's co-located USD schema

Usage: ost plugin schema <COMMAND>

Subcommands:

  • ost plugin schema add — Add a co-located schema to an existing (non-schema) bundle: write a starter schema.usda and wire the manifest so the next ost plugin build generates + links it into the same plugin library
ost plugin schema add

Add a co-located schema to an existing (non-schema) bundle: write a starter schema.usda and wire the manifest so the next ost plugin build generates + links it into the same plugin library

Usage: ost plugin schema add [OPTIONS] <BUNDLE>

Arguments:

Argument Required Description
<BUNDLE> yes Path to the bundle directory

Options:

Option Description
--class <CLASS> Source class name; the public type is , e.g. bundle toy + class MetadataAPI -> ToyMetadataAPI
--codeless Scaffold a codeless (skipCodeGeneration) schema: the build merges only the generated resources, adding no C++ to the library
--source <SOURCE> Bundle-relative path for the schema source

ost plugin test

Orchestrate the verification pyramid (L0..L6) and write a report

Usage: ost plugin test [OPTIONS] [<BUNDLE>]

Arguments:

Argument Required Description
<BUNDLE> no Path to the bundle directory (omit with --workspace)

Options:

Option Description
--from-package Test the packaged artifact, not the build tree: extract the already-built ost plugin package output to a clean directory and run discovery / open / validate against it. Catches a build-tree path baked into plugInfo/LibraryPath that source-tree discovery cannot see. Requires a prior ost plugin package. Composes with --workspace, which extracts every bundle and tests each against its dependencies' extracted trees rather than their source directories
--graph-only Validate the workspace dependency graph and stop, exiting on that result alone. Needs no build, no runtime, and no packaged artifact, so it runs as an early PR gate in milliseconds. Requires --workspace
--profile <PROFILE> Profile to test against. Defaults to the enclosing project's
--target <TARGET> Platform target, e.g. cy2026. Defaults to the enclosing project's
--up-to <UP_TO> Highest verification level to run (0..=6). Default 5; 6 adds usdview
--with <WITH> Additional plugin bundle(s) to include in the session env
--workspace Validate the dependency graph, then test every discovered bundle: immediate subdirectories and plugins/* with a plugin manifest

ost plugin test-view

Verify usdview launches on a fixture (Level 6) and write a report

Usage: ost plugin test-view [OPTIONS] <BUNDLE> <FIXTURE>

Arguments:

Argument Required Description
<BUNDLE> yes Path to the bundle directory
<FIXTURE> yes Fixture to open (relative to the bundle, or an absolute path)

Options:

Option Description
--profile <PROFILE> Profile to test against. Defaults to the enclosing project's
--target <TARGET> Platform target, e.g. cy2026. Defaults to the enclosing project's
--with <WITH> Additional plugin bundle(s) to include in the session env

ost plugin view

Open a fixture in usdview inside the plugin's runtime session (Level 6)

Usage: ost plugin view [OPTIONS] <BUNDLE> <FIXTURE>

Arguments:

Argument Required Description
<BUNDLE> yes Path to the bundle directory
<FIXTURE> yes Fixture to open (relative to the bundle, or an absolute path)

Options:

Option Description
--profile <PROFILE> Profile to activate. Defaults to the enclosing project's
--target <TARGET> Platform target, e.g. cy2026. Defaults to the enclosing project's
--with <WITH> Additional plugin bundle(s) to include in the session env

ost presets

Manage OpenStrata's CMake preset includes in CMakePresets.json

Usage: ost presets <COMMAND>

Subcommands:

  • ost presets diff — Show what install would add to CMakePresets.json, without writing
  • ost presets install — Wire OpenStrata's per-target presets into the project CMakePresets.json
  • ost presets uninstall — Remove OpenStrata-managed includes from the project CMakePresets.json

ost presets diff

Show what install would add to CMakePresets.json, without writing

Usage: ost presets diff

ost presets install

Wire OpenStrata's per-target presets into the project CMakePresets.json

Usage: ost presets install [OPTIONS]

Options:

Option Description
--backup Back up CMakePresets.json to CMakePresets.json.bak before writing
--dry-run Show the planned changes without writing

ost presets uninstall

Remove OpenStrata-managed includes from the project CMakePresets.json

Usage: ost presets uninstall [OPTIONS]

Options:

Option Description
--backup Back up CMakePresets.json to CMakePresets.json.bak before writing
--dry-run Show the planned changes without writing

ost renderer

Inspect renderer projects in host applications

Usage: ost renderer <COMMAND>

Subcommands:

ost renderer adopt

Safely adopt an existing CMake renderer without overwriting source

Usage: ost renderer adopt [OPTIONS]

Options:

Option Description
--allow-unresolved Record unresolved target labels instead of refusing the write
--backend <BACKEND> Backend mapping in KIND=TARGET form, e.g. vulkan=merlin-vulkan
--core <CORE> Existing CMake target for the host-neutral core
--extraction <EXTRACTION> Existing CMake target for renderer extraction
--headless <HEADLESS> Existing headless adapter target
--hydra2 <HYDRA2> Existing optional Hydra 2 adapter target
--name <NAME> Renderer/project identity
--platform <PLATFORM> Platform for a missing openstrata.toml
--profile <PROFILE> Host-neutral project profile for a missing openstrata.toml
--replace-manifest Replace an existing, different renderer manifest (never source/CMake)
--version <VERSION> Inline project version for a missing openstrata.toml (default 0.1.0)
--version-file <VERSION_FILE> Existing repo-relative authoritative version file to adopt
--viewport <VIEWPORT> Existing optional standalone native viewport target
--write Apply the plan. Without this flag the command is a read-only dry run

ost renderer attach-session

Attach an honest external/unverified producer session to a report

Usage: ost renderer attach-session [OPTIONS] <REPORT>

Arguments:

Argument Required Description
<REPORT> yes Renderer report produced by the external invocation

Options:

Option Description
--completed-unix <COMPLETED_UNIX> Producer completion time as Unix seconds. Required for success/failure; omitted for an incomplete producer
--out <OUT> Write to another path instead of atomically updating REPORT
--outcome <OUTCOME> Producer outcome: success, failure, or incomplete
--session-id <SESSION_ID> Stable external invocation id. Generated when omitted
--started-unix <STARTED_UNIX> Producer start time as Unix seconds
--target <TARGET> External producer's target/build identity

ost renderer merge

Merge independently produced renderer reports with conflict checks

Usage: ost renderer merge [OPTIONS]

Options:

Option Description
--base <BASE> Base renderer report
--out <OUT> Output renderer report
--overlay <OVERLAY> Overlay renderer report
--replace Explicitly replace duplicate assertion ids

ost renderer view

Open a scene in usdview with the built Hydra renderer selected

Usage: ost renderer view [OPTIONS] [<SCENE>]

Arguments:

Argument Required Description
<SCENE> no USD scene to open. Defaults to the installed usdview smoke scene

Options:

Option Description
--build-dir <BUILD_DIR> External/prebuilt Hydra CMake tree. Omit for an OST-managed build
--camera <CAMERA> Camera prim to view through. Omitted by default: the scene is inspected and a camera is used only if one is actually there, otherwise usdview opens on its free camera
--config <CONFIG> CMake configuration to install and inspect
--generator <GENERATOR> CMake generator for the managed build. Ninja remains the default
--intent <INTENT> Project-declared build intent to combine with the Hydra workflow
--profile <PROFILE> Runtime profile. Auto-selects a unique pulled usdview runtime
--renderer <RENDERER> Override the renderer display name read from installed plugInfo.json
--target <TARGET> Platform target, e.g. cy2026. Defaults to the project's platform

ost renderer viewport

Build and launch the standalone native viewport adapter

Usage: ost renderer viewport [OPTIONS] [<ARGS>]

Arguments:

Argument Required Description
<ARGS> no Arguments passed to the viewport executable after --, e.g. ost renderer viewport -- --frames 8 --hidden

Options:

Option Description
--config <CONFIG> CMake configuration to build
--generator <GENERATOR> CMake generator for the managed build. Ninja remains the default
--intent <INTENT> Project-declared build intent to combine with the viewport workflow
--preflight Resolve the intent, runtime profile, adapter, and scene capabilities, then stop before configuring or building
--profile <PROFILE> Profile for the managed build. Defaults to the project's profile; the standalone viewport needs no OpenUSD runtime
--target <TARGET> Platform target, e.g. cy2026. Defaults to the project's platform

ost runtime

Pull, list, and inspect runtimes in the local store

Usage: ost runtime <COMMAND>

Subcommands:

ost runtime explain

Explain how a profile resolves to capabilities and extensions

Usage: ost runtime explain [OPTIONS] <PLATFORM>

Arguments:

Argument Required Description
<PLATFORM> yes Platform calendar-year id, e.g. cy2026

Options:

Option Description
--profile <PROFILE> Profile, e.g. lookdev

ost runtime export

Export a pulled real runtime into the local artifact registry

Usage: ost runtime export [OPTIONS] <PLATFORM>

Arguments:

Argument Required Description
<PLATFORM> yes Platform calendar-year id, e.g. cy2026, or a full runtime id

Options:

Option Description
--build-metadata <BUILD_METADATA> JSON file describing what produced this artifact, so a producer that is not GitHub Actions can still emit provenance. Requires a non-empty source.repository, source.revision, builder.id, and a populated builder.identity object
--dist <DIST> Also keep the producer output (archive + manifest.json + SHA256SUMS) in this directory instead of a temporary staging dir
--jobs <JOBS> zstd worker threads for compression. Defaults to the host's available parallelism, or the byte-stable single-threaded encoder when SOURCE_DATE_EPOCH is set; --jobs 0 also forces it explicitly
--level <LEVEL> zstd compression level (1–22). Lower is faster; the default (19) favors a small artifact, packed once and pulled many times
--profile <PROFILE> Profile, e.g. usd
--slim Export only the SDK layout (include, lib, bin, plugin, cmake, libraries, resources, share, and CMake config), dropping the source/build tree of a runtime adopted from a full USD build. Much smaller archive and faster per-PR pull

ost runtime list

List runtimes present in the local store

Usage: ost runtime list

ost runtime pull

Materialize a runtime into the local store

Usage: ost runtime pull [OPTIONS] <PLATFORM>

Arguments:

Argument Required Description
<PLATFORM> yes Platform calendar-year id, e.g. cy2026

Options:

Option Description
--build <BUILD> Build OpenUSD from source into the store (build source), via the source tree's build_scripts/build_usd.py. Falls back to OST_USD_SRC when no path is given
--build-arg <BUILD_ARGS> Extra argument forwarded to the builder (repeatable). With build_usd.py: e.g. --build-arg --no-imaging. With --deps (CMake): e.g. --build-arg -DPXR_BUILD_IMAGING=OFF. Hyphen values allowed
--deployment-target <DEPLOYMENT_TARGET> macOS deployment target for --build (CMAKE_OSX_DEPLOYMENT_TARGET), e.g. 14.5 — the oldest macOS the produced runtime must load on
--deps <DEPS> Dependency prefix for a direct CMake build of --build (repeatable; joined into CMAKE_PREFIX_PATH). When given, OpenUSD is built with CMake against these deps instead of via build_usd.py. Falls back to OST_USD_DEPS (path-separator list)
--force Re-pull even if the runtime already exists
--from-artifact <FROM_ARTIFACT> Materialize the runtime from a registry artifact (artifact source): a digest reference (sha256:<hex> or a unique hex prefix) of an ost runtime exported artifact
--from-usd <FROM_USD> Adopt an existing OpenUSD install at this path instead of materializing a mock layout (local source). Falls back to OST_USD_ROOT when unset
--jobs <JOBS> Parallel build jobs for --build (passed to the builder as -j)
--profile <PROFILE> Profile to pull, e.g. usd or lookdev
--sdk <SDK> macOS SDK to build --build against: a full path, or a version like 15.2 resolved with xcrun --sdk macosx<version> --show-sdk-path. Sets CMAKE_OSX_SYSROOT for the whole build

ost runtime repair

Re-adopt a local runtime from its recorded USD root, refreshing the manifest (real OpenUSD version, layout, digest) after install drift

Usage: ost runtime repair [OPTIONS] <PLATFORM>

Arguments:

Argument Required Description
<PLATFORM> yes Platform calendar-year id, e.g. cy2026, or a full runtime id

Options:

Option Description
--profile <PROFILE> Profile, e.g. usd

ost runtime show

Show the manifest of a pulled runtime

Usage: ost runtime show [OPTIONS] <PLATFORM>

Arguments:

Argument Required Description
<PLATFORM> yes Platform calendar-year id, e.g. cy2026

Options:

Option Description
--profile <PROFILE> Profile, e.g. usd

ost runtime validate

Validate a pulled runtime and record the outcome in its manifest

Usage: ost runtime validate [OPTIONS] <PLATFORM>

Arguments:

Argument Required Description
<PLATFORM> yes Platform calendar-year id, e.g. cy2026

Options:

Option Description
--profile <PROFILE> Profile, e.g. usd

ost test

Run a built target's tests under the runtime that built it

Usage: ost test [OPTIONS]

Options:

Option Description
--busy-timeout <BUSY_TIMEOUT> How long --on-busy wait waits, in seconds; 0 waits indefinitely
--ctest <CTEST> Path to the ctest executable if it is not on PATH
--dry-run Print the command that would run, without executing or writing anything
--filter <FILTER> Only run tests whose name matches this regular expression (CTest -R)
--intent <INTENT> Test the build produced for this project-declared intent
--jobs <JOBS> Parallel test jobs
--no-vcvars Do not auto-load the MSVC developer environment (Windows)
--notify Fire a desktop notification when the run finishes (no-op over SSH/CI)
--on-busy <ON_BUSY> What to do when another invocation is already writing this target: fail immediately, wait for it (see --busy-timeout), or read-only to proceed without taking the target lease
--profile <PROFILE> Profile to test. Defaults to the project's profile
--progress <PROGRESS> Progress rendering: auto (human on a TTY, plain otherwise), plain, or json (one JSON event per line)
--quiet Suppress progress output; child output goes to the log
--target <TARGET> Platform target, e.g. cy2026. Defaults to the project's platform
--test-timeout <TEST_TIMEOUT> Per-test timeout in seconds; 0 disables it
--timeout <TIMEOUT> Timeout for the whole run in seconds; 0 disables it. On expiry the test process tree is terminated, not just the CTest process

ost uv

Run uv pinned to the project's runtime Python

Usage: ost uv [<ARGS>]

Arguments:

Argument Required Description
<ARGS> no Arguments passed through to uv (e.g. sync --locked)

ost validate

Validate a built/packaged target

Usage: ost validate [OPTIONS]

Options:

Option Description
--build-dir <BUILD_DIR> External/manual build tree whose evidence should be validated without claiming it was produced by ost build
--intent <INTENT> Validate the build produced for this project-declared intent
--profile <PROFILE> Profile to validate. Defaults to the project's profile
--target <TARGET> Platform target, e.g. cy2026. Defaults to the project's platform