usdq

A command-line tool and Python library for authoring and composing OpenUSD scenes through structured JSON. Every command takes plain arguments and returns JSON, so scripts and LLM agents can build USD stages without importing pxr or writing .usda by hand. The surface is self-describing: usdq verbs emits the full machine-readable spec.

pip install usdq          # CLI + daemon + MCP server; usd-core is the only dependency
usdq verbs                # the full command surface as JSON (start here)
usdq mcp                  # serve every verb as MCP tools over stdio

Agents should read AGENTS.md for the JSON contract and canonical workflows; usdq with no arguments prints the same reference.

Status

Version 0.1.2, under active development. The command surface spans three areas:

• Authoring & composition — prims and attributes, references and other composition arcs, variants, layers, collections, schemas, renaming, masked-write guards, and deferred-save sessions.
• Geometry & shading — mesh arrays, tube and ribbon meshes, point instancers, HD primitives, and textured UsdPreviewSurface material networks.
• Introspection & batching — verbs and schemas for discovery, batch for grouped execution.

The library wraps OpenUSD's pxr. The intended deployment is a thin client talking to a long-running daemon that holds the USD runtime, so repeated calls avoid repeated startup cost.

Run

pip install usdq                         # installs the `usdq` and `usdq-render` commands

usdq init /tmp/scene.usda --default-prim /World
usdq define-prim /tmp/scene.usda /World Mesh
usdq schema-info Mesh --pretty
usdq verbs --pretty

The first command auto-spawns a background daemon (per-user, on-demand) that owns the heavy USD runtime; subsequent calls reuse it. Pass --no-daemon to run in-process. For local development from a checkout: pip install -e ".[dev]".

Rendering

usdq-render adapters (usdrecord / blender / web-preview) require external tools that are not pip-installable — a full OpenUSD install for usdrecord (the usd-core wheel does not bundle it), Blender for Cycles + USD→glTF, and Chrome for web screenshots. Missing tools fail cleanly with renderer_not_found; core authoring needs none of them. See PORTABILITY.md for what survives across renderers.

Quality Gates

.venv/bin/ruff check --no-cache .
.venv/bin/pytest -q

# Optional local renderer smoke tests; not run by default in CI.
USDQ_RUN_REAL_RENDER_TESTS=1 .venv/bin/pytest -q -m real_render tests/test_render_cli.py

Design Contract

• JSON success responses go to stdout.
• Structured JSON errors go to stderr with non-zero exit codes.
• set-attr refuses writes that would be silently masked by stronger root-layer-stack opinions unless --force is passed.
• batch is deferred-save execution, not rollback-transactional execution: successful ops before a halt are persisted. The CLI exits non-zero if any submitted op fails, with the structured batch response on stderr.
• begin-session / flush-session / end-session pin one stage across daemon requests and defer persistence until an explicit flush. Daemon auto-session remains opt-in through USDQ_AUTOSESSION=1.
• The public CLI, core dispatch, and verbs manifest are generated from the same verb registry.

See DOCS.md for the full command reference and NOTES.md for the design log.