Command reference / macOS CLI

Real commands. Current output.

Sixteen working StageTrace commands, shown with sanitized excerpts from the current CLI. Every response has a versioned JSON contract for pipelines that need a stable interface.

Current boundaryComing soon on macOSWindows and Linux CLI will follow

01

Orient

Confirm the build, discover its contracts, and set the working context.

stagetrace help

implementedmacOS arm64

QuestionHow do I use a command without leaving the terminal?

Discover commands, usage, options, and exit contracts without leaving the terminal.

Run$ stagetrace help why --format json
JSON Schema
Current output excerpt
{
  "command": "help",
  "status": "ok",
  "data": {
    "name": "why",
    "summary": "Resolve a property and report the winning opinion plus property stack contributors."
  }
}

stagetrace version

implementedmacOS arm64

QuestionWhich StageTrace and OpenUSD build produced this result?

Report StageTrace, core, and bundled OpenUSD versions for reproducible diagnostics.

Run$ stagetrace version --format json
JSON Schema
Current output excerpt
{
  "command": "version",
  "status": "ok",
  "data": {
    "productName": "StageTrace",
    "executableName": "stagetrace",
    "usdVersion": "26.05",
    "expectedUsdVersion": "26.05"
  }
}

stagetrace schema

implementedmacOS arm64

QuestionWhat JSON contract does this command emit?

Inspect the exact local JSON contract used by a command or list every available contract.

Run$ stagetrace schema why --format json
JSON Schema
Current output excerpt
{
  "command": "schema",
  "status": "ok",
  "data": {
    "schemaVersion": "1.0",
    "command": "why",
    "schema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "title": "StageTrace CLI why response 1.0"
    }
  }
}

stagetrace project

implementedmacOS arm64

QuestionHow do I reopen this stage with the same session layer?

Create or reopen a local project with a persistent, versioned session layer.

Run$ stagetrace project init --root-stage Tests/Fixtures/basic_stage.usda stagetrace-example.stproj --format json

FixtureTests/Fixtures/basic_stage.usda

JSON Schema
Current output excerpt
{
  "command": "project",
  "status": "ok",
  "data": {
    "mode": "init",
    "project": { "schemaVersion": "1.0", "editTarget": "session" },
    "inspectIssueCount": 0
  }
}

stagetrace plugins

implementedmacOS arm64

QuestionWhich resolver and plugins are active?

See bundled and explicitly enabled external OpenUSD plugin paths and loaded plugins.

Run$ stagetrace plugins Tests/Fixtures/basic_stage.usda --format json

FixtureTests/Fixtures/basic_stage.usda

JSON Schema
Current output excerpt
{
  "command": "plugins",
  "status": "ok",
  "data": {
    "externalPluginPaths": [],
    "missingPlugins": [],
    "resolver": { "name": "ArDefaultResolver" }
  }
}

02

Inspect

Read the stage hierarchy, layer stack, and composition structure.

stagetrace inspect

implementedmacOS arm64

QuestionWhat is actually inside this stage?

Open a stage and inventory its prims, metadata, timing, and composition issues.

Run$ stagetrace inspect Tests/Fixtures/basic_stage.usda --load none --format json

FixtureTests/Fixtures/basic_stage.usda

JSON Schema
Current output excerpt
{
  "command": "inspect",
  "status": "ok",
  "data": {
    "defaultPrim": { "present": true, "path": "/World" },
    "layerCount": 2,
    "primCount": 3
  }
}

stagetrace layers

implementedmacOS arm64

QuestionWhich layers are participating, and in what strength order?

Read the strength-ordered layer stack, including root, session, anonymous, and muted state.

Run$ stagetrace layers Tests/Fixtures/slice4c_sublayer_root.usda --format json

FixtureTests/Fixtures/slice4c_sublayer_root.usda

JSON Schema
Current output excerpt
{
  "command": "layers",
  "status": "ok",
  "data": {
    "layers": [
      { "index": 0, "isAnonymous": true, "isSessionLayer": true, "isRootLayer": false }
    ]
  }
}

stagetrace tree

implementedmacOS arm64

QuestionHow is the prim hierarchy arranged?

Navigate a large prim hierarchy with depth and paging controls.

Run$ stagetrace tree Tests/Fixtures/slice4_tree.usda --depth 2 --page-size 50 --format json

FixtureTests/Fixtures/slice4_tree.usda

JSON Schema
Current output excerpt
{
  "command": "tree",
  "status": "ok",
  "data": {
    "rootPrim": "/",
    "page": 0,
    "pageSize": 50,
    "totalPrims": 5,
    "totalPages": 1
  }
}

stagetrace compose

implementedmacOS arm64

QuestionWhich composition arcs built this prim?

Trace a prim’s composition arcs, introducing layers and paths, and variant selections.

Run$ stagetrace compose Tests/Fixtures/slice4_compose.usda --prim /World/Referenced --format json

FixtureTests/Fixtures/slice4_compose.usda

JSON Schema
Current output excerpt
{
  "command": "compose",
  "status": "ok",
  "data": {
    "primPath": "/World/Referenced",
    "arcs": [
      { "type": "root", "targetPath": "/World/Referenced" },
      { "type": "reference", "targetPath": "/Model", "introducingPath": "/World/Referenced" }
    ]
  }
}

03

Diagnose

Follow a surprising result back to the opinion and source that produced it.

stagetrace why

implementedmacOS arm64

QuestionWhich opinion produced this value, and why did it win?

Resolve one property and correlate its value source, competing opinions, causal arc, and safe action.

Run$ stagetrace why Tests/Fixtures/diagnostic_local_over_reference.usda --prop /World/Referenced.test:size --format json

FixtureTests/Fixtures/diagnostic_local_over_reference.usda

JSON Schema
Current output excerpt
{
  "command": "why",
  "status": "ok",
  "data": {
    "propertyPath": "/World/Referenced.test:size",
    "resolvedValue": "9",
    "sourceKind": "authoredDefault",
    "winner": {
      "layer": "Tests/Fixtures/diagnostic_local_over_reference.usda",
      "path": "/World/Referenced.test:size",
      "value": "9",
      "role": "winner",
      "sourceKind": "authoredDefault",
      "arcType": "root"
    },
    "reason": "The strongest value-bearing opinion matching OpenUSD resolve information wins; weaker and metadata-only specs remain visible as competitors.",
    "competingOpinions": [
      {
        "layer": "Tests/Fixtures/slice4c_reference_model.usda",
        "path": "/Model.test:size",
        "value": "5",
        "role": "weaker",
        "arcType": "reference"
      }
    ],
    "safeEditRecommendation": {
      "canEdit": true,
      "command": "stagetrace edit <stage> --set /World/Referenced.test:size=<value> --override-out override.usda",
      "caveat": "Author into a session or override layer unless you own the source layer.",
      "action": "authorSessionOverride",
      "reason": "supportedAttributeType"
    }
  }
}

stagetrace visibility

implementedmacOS arm64

QuestionWhat actually made this prim invisible?

Compute effective visibility and identify the actual invisible ancestor and opinion.

Run$ stagetrace visibility Tests/Fixtures/diagnostic_visibility_reference_root.usda --prim /World/Referenced/Child --format json

FixtureTests/Fixtures/diagnostic_visibility_reference_root.usda

JSON Schema
Current output excerpt
{
  "command": "visibility",
  "status": "ok",
  "data": {
    "primPath": "/World/Referenced/Child",
    "computedVisibility": "invisible",
    "blockingOpinion": {
      "path": "/Model.visibility",
      "value": "invisible",
      "sourceKind": "authoredDefault",
      "arcType": "reference"
    },
    "safeEditRecommendation": {
      "canEdit": true,
      "path": "/World/Referenced.visibility",
      "action": "authorSessionOverride"
    }
  }
}

stagetrace explain

implementedmacOS arm64

QuestionHow do the diagnostic answers fit together?

Combine property, composition, visibility, layer, and editability context from one stage snapshot.

Run$ stagetrace explain Tests/Fixtures/diagnostic_default_vs_time_samples.usda --prop /World.test:size --time 1.5 --format json

FixtureTests/Fixtures/diagnostic_default_vs_time_samples.usda

JSON Schema
Current output excerpt
{
  "command": "explain",
  "status": "ok",
  "data": {
    "mode": "property",
    "timeCode": "1.5",
    "probe": { "targetKind": "attribute", "stageRevision": 1 },
    "property": {
      "resolvedValue": "15",
      "sourceKind": "timeSamples",
      "winner": { "value": "15", "timeCode": "1.5", "sourceKind": "timeSamples" }
    },
    "visibility": { "computedVisibility": "inherited" },
    "editability": { "editableByCurrentEdit": true, "propertyKind": "attribute" }
  }
}

stagetrace validate

implementedmacOS arm64

QuestionDoes this stage pass the current validation policy?

Run native OpenUSD validators and return pipeline-friendly text or JSON results.

Run$ stagetrace validate Tests/Fixtures/valid_stage.usda --fail-on warning --format json

FixtureTests/Fixtures/valid_stage.usda

JSON Schema
Current output excerpt
{
  "command": "validate",
  "status": "ok",
  "data": {
    "failOn": "warning",
    "passed": true,
    "summary": { "errors": 0, "warnings": 0, "info": 0 },
    "issues": []
  }
}

04

Act and automate

Write non-destructive overrides, export results, and repeat checks as files change.

stagetrace edit

implementedmacOS arm64

QuestionCan I author a stronger value without touching the source layer?

Author a stronger value into a new override or project session layer without touching source USD.

Run$ stagetrace edit Tests/Fixtures/slice5_edit_source.usda --set /World.test:size=9 --override-out stagetrace-example-overrides.usda --format json

FixtureTests/Fixtures/slice5_edit_source.usda

JSON Schema
Current output excerpt
{
  "command": "edit",
  "status": "ok",
  "data": {
    "propertyPath": "/World.test:size",
    "value": "9",
    "valueType": "double",
    "hadPreviousValue": false,
    "overrideOutput": { "kind": "overrides", "overwritten": false }
  }
}

stagetrace export

implementedmacOS arm64

QuestionHow do I write the result without overwriting an existing file?

Write the current override, flattened stage, or project state without replacing an existing destination by default.

Run$ stagetrace export Tests/Fixtures/basic_stage.usda --flatten-out stagetrace-example-flattened.usda --format json

FixtureTests/Fixtures/basic_stage.usda

JSON Schema
Current output excerpt
{
  "command": "export",
  "status": "ok",
  "data": {
    "outputs": [
      { "kind": "flattened", "overwritten": false }
    ]
  }
}

stagetrace watch

implementedmacOS arm64

QuestionCan I rerun a diagnostic when the stage changes?

Watch a stage and resolved dependencies, then rerun a nested command after stable changes.

Run$ stagetrace watch Tests/Fixtures/slice4_opinion_strong.usda -- why Tests/Fixtures/slice4_opinion_strong.usda --prop /World.test:size --format json

FixtureTests/Fixtures/slice4_opinion_strong.usda

JSON Schema
Current output excerpt
{
  "schemaVersion": "1.0",
  "event": "watchStarted",
  "command": [
    "why",
    "Tests/Fixtures/slice4_opinion_strong.usda",
    "--prop",
    "/World.test:size",
    "--format",
    "json"
  ],
  "exitCode": 0,
  "output": "",
  "message": "",
  "warnings": []
}

Missing a workflow?

Tell us where the trail goes cold.

A real pipeline problem is more useful than a feature request written in the abstract.

Join the waitlist