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:

With --json, add-on load failures and export failures are emitted as structured JSON with ok, schemaversion, command, error, context, artifacts, and optional processoutput; 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