tomkrikorian BlenderToRCP CLI Setup
Configure the BlenderToRCP CLI so the agent can export scenes, bake textures, validate materials, and manage settings from the terminal.
Prerequisites
- Blender 5.0+ installed
- BlenderToRCP addon installed and enabled in Blender's preferences
- Python 3 available as
python3
For manual installs, install BlenderToRCP.zip in Blender via Edit > Preferences > Extensions > Add-ons > Install from Disk..., then enable BlenderToRCP. For development installs, symlink <repo>/Plugin to the Blender extensions/user_default/BlenderToRCP path.
Inputs
blender-path(optional): explicit path to the Blender binary
Workflow
1. Locate the Blender binary
If the user supplied a path, verify it exists. Otherwise probe common locations:
# macOS
test -x /Applications/Blender.app/Contents/MacOS/Blender && echo "found"
# Linux
command -v blender >/dev/null 2>&1 && echo "found"
which blender
If nothing is found, ask the user for the path before proceeding.
2. Locate the extension root
The addon ships the CLI directly in the extension root. Check Blender's extensions paths:
# macOS
find ~/Library/Application\ Support/Blender \
\( -path "*/extensions/.local/BlenderToRCP/cli/__main__.py" -o \
-path "*/extensions/user_default/BlenderToRCP/cli/__main__.py" \) 2>/dev/null
# Linux
find ~/.config/blender \
\( -path "*/extensions/.local/BlenderToRCP/cli/__main__.py" -o \
-path "*/extensions/user_default/BlenderToRCP/cli/__main__.py" \) 2>/dev/null
For development installs, the CLI directory is <repo>/Plugin/, and the dev symlink usually points .../extensions/user_default/BlenderToRCP there.
Verify the install by confirming both cli/__main__.py and api/runner.py exist in the resolved extension root. In a repo checkout, those files live under Plugin/.
3. Test the connection
Run these checks to confirm Blender, Python, and the addon are all wired up:
# Installed extension root
BLENDERTORCP_BLENDER=/path/to/blender python3 /path/to/BlenderToRCP version
BLENDERTORCP_BLENDER=/path/to/blender python3 /path/to/BlenderToRCP preferences get
BLENDERTORCP_BLENDER=/path/to/blender python3 /path/to/BlenderToRCP settings list
# Development checkout
python3 /path/to/repo/Plugin --blender /path/to/blender version
python3 /path/to/repo/Plugin --blender /path/to/blender preferences get
python3 /path/to/repo/Plugin --blender /path/to/blender settings list
version proves Blender launches. preferences get and settings list also prove the addon registered correctly. If this fails:
| Error | Exit Code | Cause | Fix |
|---|---|---|---|
Blender not found |
2 | Wrong binary path | Correct BLENDERTORCP_BLENDER or use --blender <path> |
No output from Blender |
1 | Blender crashed on startup | Re-run with --verbose, save stderr, then create a support bundle if a scene is involved |
Failed to import command registry |
3 | Plugin path is wrong, addon not enabled, or files are missing | Enable BlenderToRCP in Blender preferences and re-check the install path |
BlenderToRCP addon preferences not available. |
1 | Add-on is not enabled, or the path points at the wrong directory | Enable the add-on, then re-run preferences get against the resolved extension root |
'Scene' object has no attribute 'blender_to_rcp_export_settings' |
1 | Add-on did not register its scene properties | Enable the add-on, then re-run settings list or settings get |
With --json, add-on load failures and export failures are emitted as structured JSON with ok, schema_version, command, error, context, artifacts, and optional process_output; without --json, the CLI prints a shorter stderr message plus diagnostics/support hints when available.
For support captures:
blendertorcp --verbose export scene.blend -o output.usdz \
> blendertorcp-result.json \
2> blendertorcp-stderr.log
blendertorcp support-bundle scene.blend -o output.usdz --diagnostics output.diagnostics.json
# For UI background bake/export failures, also pass the job directory:
blendertorcp support-bundle scene.blend -o output.usdz \
--job-dir output/.blendertorcp_jobs/bake_export_YYYYMMDD_HHMMSS_abcd
4. Configure the shell
Add to the user's shell profile (~/.zshrc, ~/.bashrc, or equivalent):
export BLENDERTORCP_BLENDER="/path/to/blender"
alias blendertorcp="python3 /path/to/BlenderToRCP"
# Or for a repository checkout:
# alias blendertorcp="python3 /path/to/repo/Plugin"
After sourcing the profile, confirm the alias works:
blendertorcp version
blendertorcp preferences get
blendertorcp settings list
5. Report result
Print the resolved paths and confirm the setup is complete:
- Blender binary path
- Extension root or repo
Plugin/path - Shell alias configured (yes/no)
- CLI verification output