CLI Tool Reference¶

blender-remote-cli is a comprehensive command-line interface that manages the entire blender-remote ecosystem, from initial setup to advanced debugging.

Overview¶

The CLI tool provides a complete workflow for blender-remote operations:

Automatic Setup: Platform-specific auto-detection of Blender installations (Windows/macOS)
Configuration Management: YAML-based settings with dot-notation access via OmegaConf
Addon Management: Automated installation and export of BLD_Remote_MCP addon
Process Control: Launch Blender in GUI or background mode with MCP service
Code Execution: Direct Python code execution in Blender with base64 encoding support
Debug Tools: Alternative TCP-based executor for testing and development
Source Code: src/blender_remote/cli/ (Click app + one module per subcommand)

Installation¶

The CLI tool is included with blender-remote:

pip install blender-remote
blender-remote-cli --help

Platform Support¶

Windows: Full support with registry-based Blender detection
macOS: Full support with Spotlight-based Blender detection
Linux: Full support with manual path configuration

Quick Start¶

Basic Workflow¶

# 1. Initialize configuration (auto-detects on Windows/macOS)
blender-remote-cli init

# 2. Install BLD Remote MCP addon
blender-remote-cli install

# 3. Start Blender with MCP service
blender-remote-cli start

# 4. Execute Python code
blender-remote-cli execute --code "print('Hello from Blender!')"

Configuration Management¶

# View all settings
blender-remote-cli config get

# Modify settings
blender-remote-cli config set mcp_service.default_port=7777

# Check connection
blender-remote-cli status

Command Reference¶

`init` - Initialize Configuration¶

Purpose: Sets up blender-remote by detecting Blender installation and creating configuration.

Usage:

blender-remote-cli init [blender_executable_path] [OPTIONS]

Arguments: - blender_executable_path (optional) - Path to Blender executable

Options: - --backup - Create backup of existing configuration file

Platform-Specific Behavior:

Windows: Searches Windows Registry for Blender 4.x installations, checks common installation paths, and searches system PATH
macOS: Uses Spotlight (mdfind) to locate Blender.app, checks standard installation locations
Linux: Prompts for manual path entry if not provided

Examples:

# Auto-detection (Windows/macOS)
blender-remote-cli init

# Specify path explicitly
blender-remote-cli init /usr/bin/blender

# Initialize with backup
blender-remote-cli init --backup

Detection Process: 1. Validates Blender version (requires 4.0+) 2. Discovers addon directories using Blender's Python API 3. Tests directory write permissions 4. Creates configuration at ~/.config/blender-remote/bld-remote-config.yaml

Generated Configuration:

blender:
  version: "4.4.3"                    # Auto-detected version
  exec_path: "/usr/bin/blender"       # Blender executable path
  root_dir: "/usr/share/blender"      # Installation directory
  plugin_dir: "/home/user/.config/blender/4.4/scripts/addons"  # Addon directory

  # Additional detected paths (informational)
  user_addons: "/home/user/.config/blender/4.4/scripts/addons"
  all_addon_paths: ["/usr/share/blender/scripts/addons", ...]
  extensions_dir: "/home/user/.config/blender/4.4/extensions"  # Blender 4.2+

mcp_service:
  default_port: 6688   # Default TCP port for MCP service
  log_level: INFO      # Logging verbosity (DEBUG, INFO, WARNING, ERROR, CRITICAL)

`install` - Install Addon¶

Purpose: Installs the BLD_Remote_MCP addon into Blender's addon directory.

Usage:

blender-remote-cli install

Auto-Detection: If no configuration exists, automatically detects Blender on Windows/macOS.

Installation Process: 1. Locates addon files (from package or development directory) 2. Creates temporary zip archive 3. Uses Blender's Python API to install addon 4. Enables addon and saves preferences 5. Verifies successful installation

Addon Locations: - Development: ./blender_addon/bld_remote_mcp/ - Installed: Retrieved from package resources - Target: {blender_addon_dir}/bld_remote_mcp/

Example Output:

[INSTALL] Installing bld_remote_mcp addon...
[ADDON] Using addon: /tmp/bld_remote_mcp.zip
Installing addon from: /tmp/bld_remote_mcp.zip
Enabling addon: bld_remote_mcp
Saving user preferences...
[SUCCESS] Addon installed successfully!
[LOCATION] Addon location: /home/user/.config/blender/4.4/scripts/addons/bld_remote_mcp

`config` - Configuration Management¶

Purpose: View and modify configuration using OmegaConf with dot notation.

`config get` - View Configuration¶

Usage:

blender-remote-cli config get [key]

Arguments: - key (optional) - Specific configuration key using dot notation

Examples:

# View all configuration
blender-remote-cli config get

# Get specific value
blender-remote-cli config get blender.version

# Get nested value
blender-remote-cli config get mcp_service.default_port

`config set` - Modify Configuration¶

Usage:

blender-remote-cli config set <key>=<value>

Type Conversion: - Integers: 7777 → 7777 - Floats: 30.5 → 30.5 - Booleans: true/false → True/False - Strings: Anything else remains string

Examples:

# Set port
blender-remote-cli config set mcp_service.default_port=7777

# Set logging level
blender-remote-cli config set mcp_service.log_level=DEBUG

# Set nested values (creates structure if needed)
blender-remote-cli config set mcp_service.advanced.timeout=45.0

`start` - Start Blender with MCP Service¶

Purpose: Launches Blender with BLD_Remote_MCP service configured and running.

Usage:

blender-remote-cli start [OPTIONS] [-- blender_args...]

Options: - --background - Run Blender headless (no GUI) - --pre-file PATH - Execute Python file before service starts - --pre-code CODE - Execute Python code before service starts - --port PORT - Override MCP service port (default: 6688) - --scene PATH - Open .blend file on startup - --log-level LEVEL - Set logging verbosity (DEBUG, INFO, WARNING, ERROR, CRITICAL)

Environment Variables Set: - BLD_REMOTE_MCP_PORT - Service port number - BLD_REMOTE_MCP_START_NOW - Always set to '1' for auto-start - BLD_REMOTE_LOG_LEVEL - Logging verbosity

Examples:

# GUI mode with default settings
blender-remote-cli start

# Background mode for automation
blender-remote-cli start --background

# Development setup
blender-remote-cli start --port=7777 --log-level=DEBUG

# Open scene with pre-execution script
blender-remote-cli start --scene=project.blend --pre-file=setup.py

# Inline code execution
blender-remote-cli start --pre-code="bpy.context.scene.render.engine='CYCLES'"

# Pass Blender arguments
blender-remote-cli start -- --factory-startup --debug-cycles

Background Mode: - Includes keep-alive script to prevent Blender from exiting - Handles SIGINT/SIGTERM for graceful shutdown - Processes queued commands via bld_remote.step() - Ideal for headless servers and CI/CD pipelines

`execute` - Execute Python Code¶

Purpose: Runs Python code in the Blender process via MCP service.

Usage:

blender-remote-cli execute [CODE_FILE] [OPTIONS]

Arguments: - CODE_FILE (optional) - Python file to execute

Options: - -c, --code TEXT - Python code string to execute - --use-base64 - Encode code as base64 before transmission - --return-base64 - Request base64-encoded results - --port PORT - Override MCP service port

Base64 Encoding: Use for code with: - Complex formatting or indentation - Special characters or nested quotes - Large scripts (>1KB) - Binary data or unicode

Examples:

# Simple inline code
blender-remote-cli execute --code "print(len(bpy.data.objects))"

# Add a cube
blender-remote-cli execute -c "bpy.ops.mesh.primitive_cube_add(location=(2,0,0))"

# Execute file
blender-remote-cli execute my_script.py

# Complex script with base64
blender-remote-cli execute complex_script.py --use-base64 --return-base64

# Custom port
blender-remote-cli execute --code "print('Hello')" --port 7777

Output:

[FILE] Executing code from: script.py
[LENGTH] Code length: 245 characters
[CONNECT] Connecting to Blender BLD_Remote_MCP service (port 6688)...
[SUCCESS] Code execution successful!
[OUTPUT] Output:
Hello from Blender!

`pkg` - Remote Package Management¶

Purpose: Manage Python packages installed into the remote Blender Python environment (site-packages) via RPC.

This is useful for both: - Online remotes (remote Blender can reach an index/PyPI), and - Offline remotes (air-gapped Blender), where the controller stages wheels locally and uploads them for offline install.

Note: Blender may report bpy.app.online_access == False by default, which should be treated as “offline” for pkg install workflows. Use the offline workflow (pkg push + pkg install --remote-wheelhouse ...) when in doubt.

Usage:

blender-remote-cli pkg [SUBCOMMAND] [OPTIONS]

Subcommands: - pkg info [--json] [--port PORT] - Probe remote Python/platform/pip info needed for packaging decisions - pkg bootstrap [--method auto|ensurepip|get-pip] [--get-pip PATH] [--upgrade] [--port PORT] - Ensure pip exists remotely - pkg install [--upgrade] [--force-reinstall] [--no-deps] [--remote-wheelhouse PATH] PACKAGE_SPEC... - Install simple package specs - pkg pip [--port PORT] -- PIP_ARGS... - Escape hatch to run arbitrary pip commands remotely - pkg push --remote-wheelhouse PATH [--chunk-size BYTES] WHEELHOUSE_OR_WHL... - Upload wheels for offline install - pkg purge-cache --remote-wheelhouse PATH [--yes] - Delete all cached wheels in the remote wheelhouse

Offline workflow example (Windows):

# Start Blender MCP service in background (runs until you stop it)
# NOTE: this command blocks the terminal that launches it
blender-remote-cli start --background

# In another terminal:
blender-remote-cli pkg info --json

# Build a local wheelhouse that matches the remote (example: py311 win_amd64)
python -m pip download -d .\\wheelhouse --only-binary=:all: --platform win_amd64 --python-version 311 --implementation cp colorama

# Upload once to a remote wheelhouse cache
blender-remote-cli pkg push .\\wheelhouse --remote-wheelhouse C:/tmp/blender-remote/wheels

# Install offline from the uploaded wheelhouse
blender-remote-cli pkg install colorama --remote-wheelhouse C:/tmp/blender-remote/wheels

# Verify import/version
blender-remote-cli execute --code "import colorama; print(colorama.__version__)"

`status` - Check Connection Status¶

Purpose: Tests connection to running BLD_Remote_MCP service.

Usage:

blender-remote-cli status

Information Displayed: - Connection status (success/failure) - Service port number - Current scene name - Object count in scene

Example Output:

Checking connection to Blender BLD_Remote_MCP service...
Connected to Blender BLD_Remote_MCP service (port 6688)
   Scene: Scene
   Objects: 3

Common Issues: - "Connection refused" - Service not running (use start command) - "Connection failed" - Wrong port or firewall blocking

`export` - Export Components¶

Purpose: Extracts addon source code or scripts for manual installation or inspection.

Usage:

blender-remote-cli export --content TYPE -o OUTPUT_DIR

Options: - --content TYPE (required) - Content to export: 'addon' or 'keep-alive.py' - -o, --output-dir PATH (required) - Output directory path

Content Types: - addon - Extracts BLD_Remote_MCP addon source to OUTPUT_DIR/bld_remote_mcp/ - keep-alive.py - Exports background mode keep-alive script

Examples:

# Export addon source
blender-remote-cli export --content addon -o ./exported

# Export keep-alive script
blender-remote-cli export --content keep-alive.py -o ./scripts

Use Cases: - Manual addon installation - Source code inspection - Custom deployment scripts - Debugging addon issues

`debug` - Debug Tools¶

Purpose: Alternative TCP-based executor for testing and development.

`debug install`¶

Usage:

blender-remote-cli debug install

Installs the simple-tcp-executor addon - a lightweight TCP server for testing code execution patterns.

`debug start`¶

Usage:

blender-remote-cli debug start [OPTIONS]

Options: - --background - Run Blender headless - --port PORT - TCP server port (default: 7777)

Environment Variable: - BLD_DEBUG_TCP_PORT - Default port if not specified

Examples:

# Start debug server in GUI mode
blender-remote-cli debug start

# Background mode with custom port
blender-remote-cli debug start --background --port 8888

Debug Features: - Simple TCP protocol (no MCP overhead) - Direct code execution without service layer - Manual step() processing in background mode - Debug logging to /tmp/blender_debug.log

Configuration Management¶

Configuration File¶

Location: Platform-specific via platformdirs: - Linux: ~/.config/blender-remote/bld-remote-config.yaml - macOS: ~/Library/Application Support/blender-remote/bld-remote-config.yaml - Windows: %APPDATA%\blender-remote\bld-remote-config.yaml

OmegaConf Features: - Type-safe value conversion - Dot notation for nested access - Graceful missing key handling - Clean YAML formatting

Backup Management:

# Create backup during init
blender-remote-cli init --backup

# Manual backup
cp ~/.config/blender-remote/bld-remote-config.yaml \
   ~/.config/blender-remote/bld-remote-config.yaml.bak

Socket Communication¶

Protocol Details: - TCP socket communication - JSON message format - Optimized chunk reading (128KB chunks) - Maximum response size: 10MB - Timeout: 60 seconds - Automatic connection cleanup

Message Format:

{
  "type": "command_type",
  "params": {
    "key": "value"
  }
}

Advanced Usage¶

Development Workflow¶

# Initialize with auto-detection
blender-remote-cli init

# Install addon
blender-remote-cli install

# Development mode with logging
blender-remote-cli start --pre-file=dev_setup.py \
  --port=7777 --scene=test.blend --log-level=DEBUG

# Test connection
blender-remote-cli status

# Execute test code
blender-remote-cli execute --code "print(bpy.app.version_string)"

Headless Automation¶

# Start background service
blender-remote-cli start --background --port=6688 &

# Wait for startup
sleep 10

# Run automation script
blender-remote-cli execute automation.py --use-base64

# Stop service
pkill -f blender

CI/CD Integration¶

# Example GitHub Actions workflow
- name: Setup Blender
  run: |
    blender-remote-cli init /usr/bin/blender
    blender-remote-cli install

- name: Run Tests
  run: |
    blender-remote-cli start --background &
    sleep 10
    blender-remote-cli execute tests/run_tests.py

Environment Variables¶

Service Control: - BLD_REMOTE_MCP_PORT - MCP service port (overrides config) - BLD_REMOTE_MCP_START_NOW - Auto-start service ('1' or 'true') - BLD_REMOTE_LOG_LEVEL - Logging verbosity

Debug Mode: - BLD_DEBUG_TCP_PORT - Debug server port (default: 7777)

Troubleshooting¶

Common Issues¶

Configuration Not Found

# Initialize first
blender-remote-cli init

# Or specify Blender path
blender-remote-cli init /path/to/blender

Auto-Detection Failed

# Windows - Check registry
reg query "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall" /s | findstr /i blender

# macOS - Use Spotlight
mdfind -name Blender.app

# Linux - Find manually
which blender
find /usr -name blender 2>/dev/null

Addon Installation Issues

# Verify Blender version (must be 4.0+)
blender --version

# Check addon directory permissions
ls -la ~/.config/blender/*/scripts/addons/

# Try manual installation
blender-remote-cli export --content addon -o /tmp
# Then install via Blender preferences

Connection Problems

# Check if service is running
ps aux | grep blender

# Test port availability
nc -zv localhost 6688

# Check firewall
sudo ufw status  # Linux

Code Execution Errors

# Use base64 for complex code
blender-remote-cli execute script.py --use-base64 --return-base64

# Check service logs
blender-remote-cli start --log-level=DEBUG

Debug Commands¶

# Verbose configuration check
blender-remote-cli config get | grep -E "port|path|version"

# Test with debug server
blender-remote-cli debug install
blender-remote-cli debug start --port 8888

# Monitor service output
blender-remote-cli start --pre-code="
import logging
logging.basicConfig(level=logging.DEBUG)
print('Debug mode active')
"

Integration Examples¶

MCP Protocol Configuration¶

{
  "mcpServers": {
    "blender-remote": {
      "command": "uvx",
      "args": ["blender-remote"],
      "env": {
        "BLD_REMOTE_LOG_LEVEL": "INFO"
      }
    }
  }
}

Python API Integration¶

import subprocess
import time
import blender_remote

# Start service via CLI
process = subprocess.Popen([
    'blender-remote-cli', 'start', '--background'
])

# Wait for service startup
time.sleep(5)

# Connect and use API
client = blender_remote.connect_to_blender(port=6688)
scene = blender_remote.create_scene_manager(client)

# Your automation code
scene.add_cube(location=(0, 0, 0))

Shell Script Automation¶

#!/bin/bash
# render_automation.sh

# Start Blender service
blender-remote-cli start --background --scene=template.blend &
BLENDER_PID=$!

# Wait for startup
sleep 10

# Run render script
blender-remote-cli execute render_script.py --use-base64

# Cleanup
kill $BLENDER_PID

Command Reference Summary¶

Command	Purpose
`init`	Initialize configuration with Blender detection
`install`	Install BLD_Remote_MCP addon
`config get/set`	View/modify configuration
`start`	Launch Blender with MCP service
`execute`	Run Python code in Blender
`pkg`	Manage remote Blender Python packages
`status`	Check service connection
`export`	Extract addon or scripts
`debug install/start`	Debug tools for development

Best Practices¶

Initial Setup: Always run init before other commands
Port Management: Use consistent ports across your workflow
Background Mode: Add proper shutdown handling in scripts
Code Execution: Use base64 for scripts >1KB or with special characters
Logging: Set appropriate log levels (INFO for production, DEBUG for development)
Error Handling: Check status before executing code
Cleanup: Properly terminate background processes

CLI Tool Reference¶

Overview¶

Installation¶

Platform Support¶

Quick Start¶

Basic Workflow¶

Configuration Management¶

Command Reference¶

init - Initialize Configuration¶

install - Install Addon¶

config - Configuration Management¶

config get - View Configuration¶

config set - Modify Configuration¶

start - Start Blender with MCP Service¶

execute - Execute Python Code¶

pkg - Remote Package Management¶

status - Check Connection Status¶

export - Export Components¶

debug - Debug Tools¶

debug install¶

debug start¶

Configuration Management¶

Configuration File¶

Socket Communication¶

Advanced Usage¶

Development Workflow¶

Headless Automation¶

CI/CD Integration¶

Environment Variables¶

Troubleshooting¶

Common Issues¶

Debug Commands¶

Integration Examples¶

MCP Protocol Configuration¶

Python API Integration¶

Shell Script Automation¶

Command Reference Summary¶

Best Practices¶

`init` - Initialize Configuration¶

`install` - Install Addon¶

`config` - Configuration Management¶

`config get` - View Configuration¶

`config set` - Modify Configuration¶

`start` - Start Blender with MCP Service¶

`execute` - Execute Python Code¶

`pkg` - Remote Package Management¶

`status` - Check Connection Status¶

`export` - Export Components¶

`debug` - Debug Tools¶

`debug install`¶

`debug start`¶