CLI Reference

Unified command-line interface for CAD-to-USD asset processing.

Overview

aif-pipeline provides a single, consistent interface for the entire asset processing workflow:

• Single entry point (aif-pipeline) for all operations

• Config-driven paths (no hardcoded values)

• Individual steps or complete pipeline execution

• Built-in help for all commands

For installation instructions, refer to Setup.

Commands

convert

Convert CAD files to USD.

aif-pipeline convert INPUT OUTPUT [options]

Option	Description	Default
--spec PATH	Converter spec JSON	From config
--concurrent N	Concurrent processes	From config
--timeout SECONDS	Timeout per file	From config
--skip-existing	Skip already converted files	false

optimize

Apply Scene Optimizer presets.

# Non-destructive (copies to output directory)
aif-pipeline optimize INPUT_DIR OUTPUT_DIR [options]

# In-place (modifies original files)
aif-pipeline optimize INPUT_DIR [options]

Option	Description	Default
--preset PATH	Scene Optimizer preset JSON	From config
--concurrent N	Concurrent processes	4
--kit-path PATH	Override Kit executable path	From config
--app APP	Override Kit app file	From config
--skip-existing	Skip files where output exists	false
--dynamic-preset	Inject native mesh paths into preset	false

validate

Validate USD assets.

aif-pipeline validate INPUT_DIR OUTPUT_DIR [options]

Option	Description	Default
--stage pre|post	Validation stage	pre
--concurrent N	Concurrent processes	10
--skip-existing	Skip already validated files	false
--fix	Apply automatic fixes	false
--output-assets PATH	Output for fixed assets (with --fix)	-
--feature NAME	Validate against a specific feature	-
--feature-version VERSION	Feature version	1.0.0
--predicate FILTER	Severity: Any, IsError, IsWarning, IsFailure	Any
--fine-grained	Per-rule timing diagnostics	false
--no-native-geometry-filter	Always run geometry checks	false

Validation Modes:

Standard (default)

Category-based validation (Basic, Usd, Omni categories).

Feature

Validate against a specific feature such as minimal_placeable_visual. Use --feature flag or set validation.mode: feature in config.

Fine-grained

Per-rule timing for diagnostics. Use --fine-grained flag (standard mode only).

metadata

Create and apply metadata for AI Factory equipment.

# Create template
aif-pipeline metadata create --type {cdu|crah|ups|gb300_rack} --output FILE

# Apply metadata to USD
aif-pipeline metadata apply INPUT --output OUTPUT --prim PRIM_NAME

# Update existing property layer from current template
aif-pipeline metadata update USDA_FILE [--type TYPE] [--dry-run]

# Convert electrical CSV to USDC
aif-pipeline metadata electrical INPUT_CSV OUTPUT_USDC --prim PRIM_NAME [--property NAME]

The update subcommand compares an existing .usda property layer against the current template. It adds missing properties and updates aif:core:assetVersion if the template defines a different value. Existing properties are never removed. Equipment type is auto-detected from aif:core:assetClass if --type is omitted.

For detailed metadata documentation, refer to Metadata.

run

Run the complete pipeline or a custom step sequence.

aif-pipeline run INPUT OUTPUT [options]

Pipeline: convert > optimize > validate (OAV/AIF rules)

Option	Description	Default
--spec PATH	Converter spec	From config
--preset PATH	Scene Optimizer preset	From config
--steps LIST	Steps to run (comma-separated)	All
--no-validate	Skip validation step	false
--skip-existing	Skip existing outputs in all steps	false

config

Manage configuration files.

Point --from at the Kit project root (the directory containing repo.bat/repo.sh for Kit App Template, or the top-level NGC extract directory). The CLI auto-detects the Kit executable and release directory inside _build/<platform>/release/ or kit/.

Windows

# Add from a Kit App Template build (contains repo.bat)
aif-pipeline config add kat_109 --from "D:/build/kit-app-template"

# Add from an NGC manual install
aif-pipeline config add ngc_109 --from "D:/build/ngc/USD_Composer_109.0.3"

# Add named configurations for different Kit versions
aif-pipeline config add kat_109 --from "D:/build/kit-app-template"
aif-pipeline config add ngc_110 --from "D:/build/ngc/USD_Composer_110.0.0"

# List and switch between configurations
aif-pipeline config list
aif-pipeline config use ngc_110

# Show current configuration
aif-pipeline config show

# Set specific values
aif-pipeline config set KEY VALUE

Linux

# Add from a Kit App Template build (contains repo.sh)
aif-pipeline config add kat_109 --from ~/kit-app-template

# Add from an NGC manual install
aif-pipeline config add ngc_109 --from ~/build/ngc/USD_Composer_109.0.3

# Add named configurations for different Kit versions
aif-pipeline config add kat_109 --from ~/kit-app-template
aif-pipeline config add ngc_110 --from ~/build/ngc/USD_Composer_110.0.0

# List and switch between configurations
aif-pipeline config list
aif-pipeline config use ngc_110

# Show current configuration
aif-pipeline config show

# Set specific values
aif-pipeline config set KEY VALUE

Configuration

Config File Locations

Location	Scope	Priority
./aif-pipeline.yaml	Project	Highest
~/.aif-pipeline/config.yaml	User (active)	Default
~/.aif-pipeline/<name>_config.yaml	User (named)	Template
--config <name or path>	One-time	Override

CLI flags (--preset, --concurrent, and so on) override specific values from any config.

Example Configuration

kit:
  # Windows - Kit App Template build:
  path: "D:/build/kit-app-template/_build/windows-x86_64/release/kit/kit.exe"
  release_dir: "D:/build/kit-app-template/_build/windows-x86_64/release"
  # Linux - Kit App Template build:
  # path: ~/kit-app-template/_build/linux-x86_64/release/kit/kit
  # release_dir: ~/kit-app-template/_build/linux-x86_64/release
  app: "my_company.my_usd_composer.kit"     # Kit application file
  cad_version: "507.1.3+109.0.0.u81f"      # CAD converter version

conversion:
  spec: scripts/data/creo_spec.json         # Converter specification file
  concurrent: 64                            # Concurrent conversion processes
  timeout: 7200                             # Timeout per file in seconds
  skip_existing: false                      # Skip files with existing outputs

optimization:
  preset: so/generic/generic_preset.json    # Scene Optimizer preset file
  concurrent: 4                             # Concurrent optimization processes
  timeout: 3600                             # Timeout per file in seconds
  skip_existing: false                      # Skip files with existing outputs
  dynamic_preset: false                     # Inject native mesh paths into preset

validation:
  mode: standard                            # standard or feature
  concurrent: 10                            # Concurrent validation processes
  timeout: 7200                             # Timeout per file in seconds
  skip_existing: false                      # Skip files with existing reports
  fix: false                                # Apply fixes automatically
  csv_output: true                          # Enable CSV output for results
  report_format: text                       # Report format: text or csv
  validator_version: null                   # Asset validator version (auto-detect)
  so_validator_version: null                # Scene Optimizer validators version
  fine_grained: false                       # Per-rule timing diagnostics
  timeout_per_rule: 600                     # Timeout per rule (fine-grained mode)
  native_geometry_filter: true              # Only run geometry checks if native geometry detected

metadata:
  types: [core]                             # Default metadata types to apply
  default_prim: Root                        # Default prim name for metadata

Environment Variables

export AIF_KIT_PATH=/path/to/kit
export AIF_KIT_RELEASE_DIR=/path/to/release

CLI Compared to Direct Scripts

The CLI wraps scripts in scripts/ with a unified interface:

CLI (Recommended)

aif-pipeline convert input/ output/ --concurrent 64
aif-pipeline optimize output/ optimized/
aif-pipeline validate optimized/ validation/

Direct Scripts

python scripts/cad_convert.py input/ output/ spec.json --num_concurrent 64
python scripts/optimize.py output/ --preset preset.json --kit_path D:/kit/kit.exe
python scripts/validate.py output/ validation/ --kit_path D:/kit/kit.exe

Troubleshooting

Command Not Found / Import Errors

Ensure your virtual environment is active (.venv prefix in the terminal prompt), or use uv run. If issues persist, re-sync:

uv sync --reinstall

Kit Path Not Configured

aif-pipeline config set kit.path "D:/path/to/kit.exe"       # Windows
# aif-pipeline config set kit.path ~/path/to/kit/kit       # Linux

See also

• Setup - Installation and initial configuration

• Scripts - Direct script reference

• Scene Optimizer Presets - Optimization presets