help
Discover commands, usage, options, and exit contracts without leaving the terminal.
$ stagetrace help why --format jsonJSON Schema {
"command": "help",
"status": "ok",
"data": { "command": "why", "summary": "Resolve a property…" }
}CLI / Command gallery
One small command
per debugging question.
Implemented macOS arm64 development commands, with sanitized excerpts from committed fixture runs and a direct link to each versioned JSON contract.
Read the samples as evidence of shape and workflow.Schema validation proves structure; direct OpenUSD comparisons test diagnostic semantics.
schema
Inspect the exact local JSON contract used by a command or list every available contract.
$ stagetrace schema why --rawJSON Schema {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "StageTrace CLI why response 1.0"
}project
Create or reopen a local project with a persistent, versioned session layer.
$ stagetrace project open shot.stproj --format jsonJSON Schema {
"command": "project",
"status": "ok",
"data": { "operation": "open", "schemaVersion": "1.0" }
}version
Report StageTrace, core, and bundled OpenUSD versions for reproducible diagnostics.
$ stagetrace version --format jsonJSON Schema {
"command": "version",
"status": "ok",
"data": { "productName": "StageTrace", "usdVersion": "v26.05" }
}inspect
Open a stage and inventory its prims, metadata, timing, and composition issues.
$ stagetrace inspect shot.usd --load none --format jsonJSON Schema {
"command": "inspect",
"status": "ok",
"data": { "defaultPrim": { "present": true, "path": "/World" } }
}validate
Run native OpenUSD validators and return pipeline-friendly JSON or SARIF.
$ stagetrace validate shot.usd --fail-on warning --format jsonJSON Schema {
"command": "validate",
"status": "issues",
"data": { "summary": { "errors": 0, "warnings": 1 } }
}plugins
See bundled and explicitly enabled external OpenUSD plugin paths and loaded plugins.
$ stagetrace plugins shot.usd --format jsonJSON Schema {
"command": "plugins",
"status": "ok",
"data": { "bundledPluginPaths": ["<RUNTIME>/plugin/usd"] }
}layers
Read the strength-ordered layer stack, including root, session, anonymous, and muted state.
$ stagetrace layers shot.usd --format jsonJSON Schema {
"command": "layers",
"status": "ok",
"data": { "layers": [{ "index": 0, "isSessionLayer": true }] }
}tree
Navigate a large prim hierarchy with depth and paging controls.
$ stagetrace tree shot.usd --depth 2 --page-size 50 --format jsonJSON Schema {
"command": "tree",
"status": "ok",
"data": { "page": 0, "pageSize": 50, "totalPages": 2 }
}compose
Trace a prim’s composition arcs, introducing layers and paths, and variant selections.
$ stagetrace compose shot.usd --prim /World/Car --format jsonJSON Schema {
"command": "compose",
"status": "ok",
"data": { "primPath": "/World/Car", "arcs": [{ "type": "reference" }] }
}why
Resolve one property and correlate its value source, competing opinions, causal arc, and safe action.
$ stagetrace why shot.usd --prop /World/Car.visibility --format jsonJSON Schema {
"command": "why",
"status": "ok",
"data": {
"resolvedValue": "invisible",
"sourceKind": "authoredDefault",
"winner": { "layer": "<ASSET>/lighting.usda", "arcType": "reference" },
"safeEditRecommendation": { "canEdit": true, "action": "authorSessionOverride" }
}
}visibility
Compute effective visibility and identify the actual invisible ancestor and opinion.
$ stagetrace visibility shot.usd --prim /World/Car/Wheel --format jsonJSON Schema {
"command": "visibility",
"status": "ok",
"data": {
"computedVisibility": "invisible",
"blockingOpinion": { "path": "/World/Car.visibility", "value": "invisible" }
}
}explain
Combine property, composition, visibility, layer, and editability context from one stage snapshot.
$ stagetrace explain shot.usd --prop /World/Car.visibility --format jsonJSON Schema {
"command": "explain",
"status": "ok",
"data": {
"mode": "property",
"probe": { "stageRevision": 1 },
"property": { "resolvedValue": "invisible" },
"visibility": { "computedVisibility": "invisible" }
}
}edit
Author a stronger value into a new override or project session layer without touching source USD.
$ stagetrace edit shot.usd --set /World/Car.visibility=inherited --override-out fix.usda --format jsonJSON Schema {
"command": "edit",
"status": "ok",
"data": { "propertyPath": "/World/Car.visibility", "sourceModified": false }
}export
Write the current override, flattened stage, or project state without replacing an existing destination by default.
$ stagetrace export shot.usd --flatten-out review.usda --format jsonJSON Schema {
"command": "export",
"status": "ok",
"data": { "flattenedPath": "review.usda", "sourceModified": false }
}watch
Watch a stage and resolved dependencies, then rerun a nested command after stable changes.
$ stagetrace watch shot.usd -- stagetrace why shot.usd --prop /World/Car.visibility --format jsonJSON Schema {
"schemaVersion": "1.0",
"event": "commandResult",
"file": "shot.usd",
"exitCode": 0
}Have a missing workflow?