usdq 0.1.0

JSON-native OpenUSD authoring for agents and humans — a verb CLI + daemon + MCP server over pxr.

usdq

JSON-native authoring and composition for OpenUSD, designed for agents (and pipeline tooling) to drive without embedding pxr directly. Every command emits JSON; the entire surface is self-describing.

pip install usdq          # the CLI + daemon + MCP server; usd-core is the only dep
usdq verbs                # the full machine-readable command surface (start here)
usdq mcp                  # expose every verb as MCP tools over stdio (for agents)

For agents: read AGENTS.md — the contract, discovery, and the canonical authoring workflows. usdq with no args prints the same breadcrumb.

Status

Experimental prototype (0.1.0), but no longer a three-verb throwaway. The current surface is 61 public verbs across:

• USD plumbing: init, define-prim, define-over, define-attr, set-attr, set-primvar, block-attr, clear-attr, set-visibility, set-active, set-purpose, set-kind, set-instanceable, set-rel, rename-prim, metadata/customData, collections, composition arcs, mutation layers, variants, schema application, deferred-save sessions, ls, explain, bbox, asset-info, layers, layer-delta, schema-info
• Canonical-pattern sugar: generic Mesh arrays, ribbon/tube Meshes, PointInstancer arrays, HD mesh primitives, textured UsdPreviewSurface material networks, material binding, transform authoring
• Machine introspection: verbs, schemas
• Batched execution: batch

The Python implementation wraps OpenUSD's pxr package. The production shape is a small client talking to a long-running daemon that owns the heavy USD runtime.

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.