CLI: rename the binary to crust, add render and ls <kind> subcommands

[doubleailes]

Summary

Binary renamed to crust. The package stays crust-render, so -p crust-render, the crate directory and Cargo.lock are unchanged. A [[bin]] name = "crust" target sets the executable name, and the clap command name is set explicitly. --log-file now writes crust-<UTC stamp>.log.

Subcommands (breaking change for command lines).

• crust render [flags] behaves like the old bare crust-render [flags]: every render flag belongs to it, --log-file included, and without -i it still renders the procedural scene.
• -l/--level is global and can go before or after the subcommand.
• --log-file stays a render flag. Its directory is optional, so before a subcommand name or ls's KIND it would take that word as the directory.
• Running with no subcommand, or crust -i scene.usda, is now a usage error.

crust ls <KIND> -i <scene>. KIND is a clap value enum: camera, light or material, with the plurals also accepted. It prints one absolute prim path per line on stdout, each path once. The log goes to stderr, so the list can be piped, for example for cam in $(crust ls camera -i shot.usda); do crust render … --camera "$cam"; done.

The listing lives in crust-core as Scene::list_usd(path, ListKind) (usd_import/listing.rs). It follows the importer's own rules, so the list matches what a render would use:

• It opens the stage in the same streaming chunks and uses the same prune_reason. It reads only the listed schema and builds nothing.
• camera: exactly the paths --camera accepts. A camera under an invisible parent is listed, because the render still walks there for cameras. Cameras inside instances or under a PointInstancer are left out.
• light: the six UsdLux types the importer reads, pruned the way geometry is, so invisible lights are left out. A light is listed whatever its values: one the importer refuses for a zero size or a collapsing transform is skipped with a warning at render time, since validity depends on the frame.
• material: every Material a binding can reach. Only materials under inactive parents or inside instances are left out.

docs/architecture.md § Invariants now lists the importer walk and this listing walk as a pair that must change together.

Scripts and docs.

• Every invocation now uses crust render / cargo run --release -- render: scripts, docs/, the openspec CLI spec and design record, the README, CLAUDE.md, the user site, and the sample comments.
• bench_ab.sh checks whether each binary has the render subcommand, so it can still compare a build from before this PR against a new one.
• The CLI reference page has a new ls section.

Not changed: the software header written into EXR and TIFF files still reads crust-render <version>.

Testing

• cargo test --workspace --no-fail-fast: 1413 passed, 0 failed. cargo clippy --workspace --all-targets -D warnings and cargo fmt --check are clean.
• list_usd_lists_what_a_render_uses uses a stage with cameras, lights and materials under invisible, inactive, class and proxy parents, in an instance, and under a PointInstancer, plus a zero-radius light.
  • It renders through every camera listed and checks the light count against the importer's light list.
  • It covers a USD layer renamed .obj, which must be refused.
  • It covers a typed sole top-level prim with four streamed children, which must be listed once.
  • It runs on both a single-stage and a streamed import.
• The CLI tests cover the subcommand structure, -l before and after the subcommand, --log-file refused outside render, every kind and its plural, and an unknown kind. A clap debug_assert checks the command definition.
• Ran the built binary by hand: crust render on the Cornell box, crust ls camera|light|material, a stage path that doesn't exist (exit 1), and the old command-line form (usage error).
• scripts/check_images.sh record/check reports every scene bit-identical, except Kitchen_set, whose assets aren't in the environment. scripts/bench_ab.sh ran a binary from before this PR against the new one.
• Not run: the Zola site build, because Zola isn't installed in this environment. The docs workflow will check the new #ls anchor.

🤖 Generated with Claude Code

https://claude.ai/code/session_012dHmaZERNCXcMkLmHQypdL

[qodo-code-review]

PR Summary by Qodo

Rename CLI to crust and add render and USD listing commands

✨ Enhancement 📝 Documentation 🧪 Tests 🕐 40+ Minutes

AI Description

• Rename the executable to crust and require render for existing rendering behavior.

Diagram

graph TD
  CLI["crust CLI"] --> Render["Render command"] --> Stage["USD stage"]
  CLI --> Ls["List command"] --> API["Scene list API"] --> Walk["Listing walk"] --> Stage
  CLI --> Logging["Command logging"] --> Stream["Terminal stream"]
  Ls --> Logging

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Share a lightweight traversal policy with the importer

• ➕ Could prevent listing and rendering prune rules from drifting apart.
• ➖ Requires refactoring established import traversal and accommodating different rules for cameras, lights and materials.

Recommendation: Keep the separate schema-only listing walk for this change: it avoids building a scene and limits risk to the existing importer. The paired-walk invariant and integration test are important safeguards; consider extracting shared traversal policy if future importer changes make synchronization difficult.

Files changed (42) +856 / -259

Enhancement (7) +440 / -93

lib.rsExport USD listing kind +1/-1

Export USD listing kind

• Re-exports 'ListKind' for callers of the new scene-listing API.

crates/crust-core/src/lib.rs

scene.rsExpose scene listing API +30/-0

Expose scene listing API

• Adds 'Scene::list_usd' and documents the camera, light and material selection rules.

crates/crust-core/src/scene.rs

listing.rsList USD prims without building a scene +156/-0

List USD prims without building a scene

• Adds a streaming stage walk that collects absolute paths using kind-specific importer pruning rules. It reads the requested schemas without constructing render geometry or materials.

crates/crust-core/src/scene/usd_import/listing.rs

mod.rsRegister the USD listing module +3/-0

Register the USD listing module

• Wires the listing implementation into the importer and documents its responsibility.

crates/crust-core/src/scene/usd_import/mod.rs

logging.rsRoute logs by command +22/-3

Route logs by command

• Keeps render logs on stdout, sends listing logs to stderr, and names timestamped log files with the 'crust' prefix.

crates/crust-render/src/logging.rs

main.rsDispatch render and ls subcommands +212/-83

Dispatch render and ls subcommands

• Moves render flags under 'render', makes logging flags global, and adds listing with singular or plural kinds. Updates parser tests for required subcommands and argument behavior.

crates/crust-render/src/main.rs

bench_ab.shCompare old and new CLI binaries +16/-6

Compare old and new CLI binaries

• Detects whether each binary supports 'render', allowing the benchmark to compare builds from either side of the CLI change.

scripts/bench_ab.sh

Tests (1) +117 / -0

usd_scene.rsTest listing against imported scenes +117/-0

Test listing against imported scenes

• Checks path order and pruning for cameras, lights and materials, verifies listed cameras can be selected for rendering, and covers a sample stage and missing input.

crates/crust-core/tests/usd_scene.rs

Documentation (27) +276 / -148

CLAUDE.mdRefresh contributor CLI examples +10/-9

Refresh contributor CLI examples

• Uses 'crust render' in run and profiling examples, adds a listing example, and distinguishes the crate from its binary.

CLAUDE.md

README.mdDocument the renamed CLI and listing command +30/-24

Document the renamed CLI and listing command

• Migrates rendering examples to the required subcommand and introduces camera and light listing examples.

README.md

make.rsRefresh auto-texture conversion reference +1/-1

Refresh auto-texture conversion reference

• Changes the CLI name mentioned in the module documentation.

crates/crust-assets/src/tiled/make.rs

maketx.rsRefresh auto-texture CLI reference +1/-1

Refresh auto-texture CLI reference

• Changes the executable name in the example's conversion documentation.

crates/crust-render/examples/maketx.rs

alab_profile.mdMigrate ALab profiling commands +6/-6

Migrate ALab profiling commands

• Uses 'crust render' in profiling recipes and updates the process-name lookup.

docs/alab_profile.md

architecture.mdRecord the paired import and listing walks +9/-2

Record the paired import and listing walks

• Identifies the renamed binary and documents the requirement to keep listing traversal aligned with import traversal.

docs/architecture.md

color_management.mdMigrate color-diagnostic render commands +3/-3

Migrate color-diagnostic render commands

• Adds 'render' to renderer invocations in color and texture troubleshooting recipes.

docs/color_management.md

material_fidelity.mdRefresh fidelity wrapper terminology +1/-1

Refresh fidelity wrapper terminology

• Names the 'crust' executable when explaining why the fidelity suite uses a wrapper.

docs/material_fidelity.md

moana_profile.mdMigrate Moana profiling examples +6/-6

Migrate Moana profiling examples

• Adds 'render' to updated Cargo and direct-binary profiling recipes.

docs/moana_profile.md

ptex_streaming.mdMigrate Ptex comparison recipes +4/-4

Migrate Ptex comparison recipes

• Adds the required 'render' subcommand to renderer invocations.

docs/ptex_streaming.md

shading_performance.mdUpdate shading profiler invocation +1/-1

Update shading profiler invocation

• Uses the renamed binary and 'render' subcommand in the callgrind recipe.

docs/shading_performance.md

subsurface_walk.mdUpdate subsurface profiling invocations +2/-2

Update subsurface profiling invocations

• Uses 'crust render' in direct render and callgrind commands.

docs/subsurface_walk.md

config.yamlIdentify the CLI binary in project context +1/-1

Identify the CLI binary in project context

• Clarifies that the 'crust-render' crate produces the 'crust' executable.

openspec/config.yaml

design.mdUpdate CLI design recipes +37/-28

Update CLI design recipes

• Migrates render recipes and records listing kinds, global flags, log naming and the paired-walk constraint.

openspec/specs/cli/design.md

spec.mdSpecify required commands and listing behavior +49/-4

Specify required commands and listing behavior

• Defines subcommand parsing, listed prim kinds and output streams, with scenarios for valid and invalid listing requests.

openspec/specs/cli/spec.md

aovs.usdaUpdate AOV sample command +1/-1

Update AOV sample command

• Adds 'render' to the scene's usage comment.

samples/aovs.usda

aovs_lpe.usdaUpdate LPE sample command +1/-1

Update LPE sample command

• Adds 'render' to the scene's usage comment.

samples/aovs_lpe.usda

hair.usdaUpdate hair sample command +1/-1

Update hair sample command

• Adds 'render' to the scene's usage comment.

samples/hair.usda

materialx_cutout.usdaUpdate cutout sample command +1/-1

Update cutout sample command

• Adds 'render' to the scene's usage comment.

samples/materialx_cutout.usda

materialx_emissive.usdaUpdate emissive sample command +1/-1

Update emissive sample command

• Adds 'render' to an example invocation in the scene comments.

samples/materialx_emissive.usda

materialx_subsurface.usdaUpdate subsurface sample command +1/-1

Update subsurface sample command

• Adds 'render' to the scene's usage comment.

samples/materialx_subsurface.usda

ptex_quads.usdaUpdate Ptex sample commands +2/-2

Update Ptex sample commands

• Adds 'render' to the comparison commands in the scene comments.

samples/ptex_quads.usda

gen_subdiv_stress.pyRefresh subdivision benchmark instructions +2/-2

Refresh subdivision benchmark instructions

• Uses 'crust render' in the generated-scene profiling examples.

scripts/gen_subdiv_stress.py

overview.mdClarify the distributed executable name +1/-1

Clarify the distributed executable name

• Distinguishes the 'crust-render' crate from its 'crust' binary in the crate overview.

site/content/docs/architecture/overview.md

quick-start.mdUpdate installation and first-render instructions +11/-11

Update installation and first-render instructions

• Names the distributed 'crust' binary and migrates quick-start commands to 'crust render'.

site/content/docs/getting-started/quick-start.md

command-line.mdDocument the render and ls command interface +87/-27

Document the render and ls command interface

• Rewrites the synopsis and examples for subcommands, explains global flags, and adds listing kinds, pruning rules and pipeable output.

site/content/docs/reference/command-line.md

environment-variables.mdMigrate environment-variable examples +6/-6

Migrate environment-variable examples

• Uses 'crust render' in commands demonstrating renderer environment variables.

site/content/docs/reference/environment-variables.md

Other (7) +23 / -18

Cargo.tomlName the executable crust +5/-0

Name the executable crust

• Adds an explicit 'crust' binary target while retaining the 'crust-render' package name.

crates/crust-render/Cargo.toml

alab-seq.nuUse crust for ALab sequence renders +1/-1

Use crust for ALab sequence renders

• Invokes the renamed binary with 'render' for each frame.

scripts/alab-seq.nu

bench_scenes.shRun scene benchmarks through crust render +4/-4

Run scene benchmarks through crust render

• Updates the binary path, benchmark invocation and profiling example.

scripts/bench_scenes.sh

check_images.shUse crust render for image checks +3/-3

Use crust render for image checks

• Updates the binary path and both image-recording and comparison render calls.

scripts/check_images.sh

gen_texture_alias_scene.pyMigrate texture-alias render calls +5/-5

Migrate texture-alias render calls

• Updates documented commands and the Python render helper to invoke 'crust render'.

scripts/gen_texture_alias_scene.py

goldeneye_suite.pyInvoke crust render from Goldeneye +3/-3

Invoke crust render from Goldeneye

• Updates the default binary path and wrapper invocation while retaining its EXR conversion behavior.

scripts/material_fidelity/goldeneye_suite.py

run.pyInvoke crust render in fidelity runs +2/-2

Invoke crust render in fidelity runs

• Updates the default binary path and per-shot subprocess command.

scripts/material_fidelity/run.py

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. A bare log flag blocks the next command ✓ Resolved

Description

The global --log-file option accepts an optional arbitrary directory value, so a following
render token can be consumed as that value instead of parsed as a subcommand. For `crust
--log-file render -i scene.usda, parsing then reaches -i` at the root, where it is not a valid
flag.

Code

crates/crust-render/src/main.rs[R45-49]

+        num_args = 0..=1,
+        default_missing_value = ".",
+        global = true
+    )]
+    log_file: Option<std::path::PathBuf>,

Relevance

●●● Strong

Recent CLI reviews accept parsing and command-behavior fixes; consuming a subcommand as an optional
path is a direct regression.

PR-#153
PR-#198

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The newly global option accepts zero or one PathBuf value, for which render is a valid string.
Existing tests cover a bare flag followed by another option and an explicit directory before a
subcommand, but not a bare flag immediately before one.

crates/crust-render/src/main.rs[32-49]
crates/crust-render/src/main.rs[52-70]
crates/crust-render/src/main.rs[790-809]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A bare `--log-file` before `render` can consume the subcommand as its optional directory.
## Fix Focus Areas
- crates/crust-render/src/main.rs[42-49]
- crates/crust-render/src/main.rs[790-809]
## Recommended Fix
Make the optional directory syntax unambiguous before subcommands, and add parser tests for bare `--log-file` immediately before both `render` and `ls`.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Two render recipes now fail ✓ Resolved

Description

The Moana traversal-stats recipe still invokes the removed crust-render binary, while the HDR
sample’s second render command passes -i without the required render subcommand. Following
either recipe after building this PR fails before rendering; the HDR sample also leaves no hdr.exr
for its subsequent exr_diff step.

Code

crates/crust-render/src/main.rs[57]

+    Render(Box<RenderArgs>),

Relevance

●●● Strong

Recent documentation reviews accepted corrections to stale commands and unreproducible recipes,
especially after CLI changes.

PR-#167
PR-#184

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The [[bin]] entry names the executable crust, but docs/moana_profile.md line 691 still invokes
target/tstats/release/crust-render -i. In samples/materialx_emissive.usda, the first command
includes render, while lines 29–30 call cargo run --release -- followed directly by -i; the
new cli_subcommands test confirms that passing -i without a subcommand is an error.

crates/crust-render/Cargo.toml[9-12]
crates/crust-render/src/main.rs[52-70]
docs/moana_profile.md[690-691]
samples/materialx_emissive.usda[28-31]
samples/materialx_emissive.usda[26-31]
crates/crust-render/src/main.rs[1109-1112]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Two render recipes still use the removed binary or pass render flags without the required `render` subcommand.

## Fix Focus Areas
- docs/moana_profile.md[690-691]
- samples/materialx_emissive.usda[28-31]

## Recommended Fix
Replace the Moana traversal-stats command with `target/tstats/release/crust render -i $ISLAND --camera /island/cam/shotCam -s 1 --stats -l debug > island.log`. Change the HDR sample’s second command to `CRUST_TEX_STREAM=1 cargo run --release -- render \` so its continued `-i samples/materialx_emissive.usda -o hdr.exr` arguments reach the render subcommand.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Non-USD files reach stage listing ✗ Dismissed

Description

Scene::list_usd forwards an unchecked Path to list_prims, which opens it with
Stage::builder().open without validating its suffix. Any crust ls ... -i path, including .obj
or .ron, therefore reaches the USD parser instead of being rejected before loading.

Code

crates/crust-core/src/scene/usd_import/listing.rs[R35-37]

+    let index = Stage::builder()
+        .load(InitialLoadSet::LoadNone)
+        .open(path_str)

Relevance

●●● Strong

Accepted pattern favors validating malformed or unsupported inputs before parsing; this directly
violates the documented USD-only contract.

PR-#198

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The checklist requires scene-loading paths to recognize only .usda, .usdc, and .usdz. The new
listing loader converts the unrestricted CLI path and calls the USD stage opener without an
extension check, so non-USD paths can enter the scene-loading path.

Rule 2230647: Restrict scene loading to USD formats only
crates/crust-render/src/main.rs[64-69]
crates/crust-core/src/scene/usd_import/listing.rs[27-40]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new stage-listing path accepts arbitrary input paths and passes them directly to the USD stage loader, allowing non-USD files to be interpreted as scenes instead of being rejected.

## Fix Focus Areas
- crates/crust-core/src/scene/usd_import/listing.rs[27-40]
- crates/crust-render/src/main.rs[64-69]

## Recommended Fix
Validate the input extension before opening the stage and accept only `.usda`, `.usdc`, and `.usdz`; return the existing unsupported-format error for every other extension.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View medium (2)

4. Stage listings can repeat the same prim ✓ Resolved

Description

collect starts at the stage root for every streamed chunk and appends matching ancestors without
deduplicating them. When a stage has one top-level camera, light, or material prim with at least
four children, that prim appears once per chunk rather than once in the listing.

Code

crates/crust-core/src/scene/usd_import/listing.rs[R52-53]

+            let stage = open_stage(path, path_str, Some(chunk))?;
+            collect(&stage, kind, &mut prims);

Relevance

●●● Strong

Recent importer precedents accept fixes for incorrect aggregation and repeated traversal results
across streaming or instancing paths.

PR-#190

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

stream_roots streams the children of a sole top-level prim when there are at least four. Masked
stages retain that prim as an ancestor, and each call to collect visits it from / and appends it
to the same vector.

crates/crust-core/src/scene/usd_import/mod.rs[123-157]
crates/crust-core/src/scene/usd_import/mod.rs[168-177]
crates/crust-core/src/scene/usd_import/mod.rs[649-658]
crates/crust-core/src/scene/usd_import/listing.rs[45-55]
crates/crust-core/src/scene/usd_import/listing.rs[75-83]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A typed ancestor retained in every masked chunk is printed repeatedly by `Scene::list_usd`.
## Fix Focus Areas
- crates/crust-core/src/scene/usd_import/listing.rs[45-55]
- crates/crust-core/src/scene/usd_import/listing.rs[75-83]
## Recommended Fix
Deduplicate emitted paths across chunks while preserving first-seen namespace order, and test a typed sole top-level prim with at least four children.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. Skipped lights still appear in listings ✗ Dismissed

Description

is_kind lists lights by USD schema without applying the dimension checks used by the light
emitters. A stage containing a zero-radius sphere light or zero-width rect light therefore lists
prims that the renderer omits from its light set.

Code

crates/crust-core/src/scene/usd_import/listing.rs[R146-149]

+        ListKind::Light => {
+            matches!(SphereLight::get(stage, path()), Ok(Some(_)))
+                || matches!(RectLight::get(stage, path()), Ok(Some(_)))
+                || matches!(DiskLight::get(stage, path()), Ok(Some(_)))

Relevance

●●● Strong

Listing promises parity with renderer output; recent correctness reviews accepted fixes preventing
invalid data from entering downstream results.

PR-#198

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

An existing test defines four invalid typed lights and asserts that import retains only the fifth,
valid light. The new listing recognizes all five by schema, while the emitters return before adding
the invalid ones.

crates/crust-core/tests/usd_inline.rs[2222-2238]
crates/crust-core/src/scene/usd_import/lights.rs[259-279]
crates/crust-core/src/scene/usd_import/lights.rs[512-521]
crates/crust-core/src/scene/usd_import/listing.rs[142-154]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`ls light` includes typed lights whose invalid dimensions cause the importer to skip them.
## Fix Focus Areas
- crates/crust-core/src/scene/usd_import/listing.rs[142-154]
- crates/crust-core/src/scene/usd_import/lights.rs[259-279]
- crates/crust-core/src/scene/usd_import/lights.rs[512-521]
## Recommended Fix
Share or reuse the importer's light-eligibility checks in listing, and test the existing invalid-light fixture against `Scene::list_usd`.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Compliance rules (platform): 127 rules

✅ Cross-repo context — repo relationships

Review mode: Auto: 🧠 Deep: Broad CLI, logging, USD traversal, scripts, and API changes create dense independent risks.

Tip of the day

💡 Did you know, you can add REVIEW.md to your repo root and Qodo follows it on every PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗