Blender Build-Go (bgo)

Automate the complete workflow from building to launching Blender with your extension/add-on installed and enabled.

When to use this skill

Use

/bgo

when:

• You want to quickly test extension/add-on changes in a fresh Blender instance
• You need to execute the full build → remove → install → enable → launch cycle
• You want to run a custom packaging script and automatically launch Blender
• You're iterating rapidly and want one command to see results

Quick Start

Auto-detect workflow (recommended):

/bgo

The skill will:

1. Detect whether you're working with an extension (Blender 4.2+) or add-on (legacy)
2. Build/package your code
3. Remove old version from Blender
4. Install fresh build
5. Enable the extension/add-on
6. Launch Blender

With custom script:

/bgo --script build_custom.py

Runs your custom packaging script, then proceeds with install/enable/launch.

Core Workflow

Step 1: Build/Package

For Extensions (Blender 4.2+):

• Validates

  blender_manifest.toml

• Builds extension as

  .zip

  using

  blender --command extension build

• Stores output in

  ./build/

  directory

For Legacy Add-ons:

• Packages add-on files (

  .py

  or directory)
• Prepares for installation via Blender preferences

For Custom Scripts:

• Executes your specified script
• Expects script to produce installable package

Step 2: Remove Old Version

For Extensions:

blender --command extension remove <extension_id>

For Add-ons:

bpy.ops.preferences.addon_disable(module="<module_name>")
bpy.ops.preferences.addon_remove(module="<module_name>")

Ensures clean slate before installation.

Step 3: Install

For Extensions:

blender --command extension install-file ./build/<package>.zip

For Add-ons:

• Copies to Blender scripts directory
• Installs via

  bpy.ops.preferences.addon_install()

Step 4: Enable

For Extensions: Extensions are typically auto-enabled on install. Verifies enabled state.

For Add-ons:

bpy.ops.preferences.addon_enable(module="<module_name>")

Step 5: Launch Blender

Opens Blender with the extension/add-on active:

blender

Or with specific options:

blender --log "*" --log-level 0  # With debug logging
blender --python-expr "import bpy; print(bpy.context.preferences.addons.keys())"  # Verify load

Usage Patterns

Pattern 1: Quick iteration (default)

/bgo

Auto-detects project type and executes full workflow. Best for rapid development cycles.

Pattern 2: Custom build script

/bgo --script scripts/build_release.py

Useful when you have:

• Custom packaging logic
• Multi-target builds
• Pre/post-build hooks
• Version management automation

Pattern 3: Specific extension/add-on

/bgo --source-dir ./my_extension --extension-id my_extension_id

Explicitly specify:

• --source-dir

  : Path to extension/add-on source

• --extension-id

  or

  --module

  : Extension ID or add-on module name

• --output-dir

  : Custom build output directory (default:

  ./build

  )

Pattern 4: Build with options

/bgo --validate-only  # Just validate, don't install/launch
/bgo --no-launch      # Build and install, but don't open Blender
/bgo --clean          # Remove build artifacts before building

Workflow Checklist

When

/bgo

executes, it performs:

Blender Build-Go Progress:
- [ ] Step 1: Detect project type (extension vs add-on)
- [ ] Step 2: Validate manifest/structure
- [ ] Step 3: Build/package code
- [ ] Step 4: Remove old version from Blender
- [ ] Step 5: Install fresh build
- [ ] Step 6: Enable extension/add-on
- [ ] Step 7: Launch Blender
- [ ] Step 8: Verify successful load

Step 1: Detection

Checks for

blender_manifest.toml

(extension) or

bl_info

(add-on) to determine workflow.

Step 2: Validation

Runs appropriate validation:

• Extensions: Manifest validation via

  validate_manifest.py

• Add-ons: Structure check for required

  bl_info

  fields

Step 3: Build

Executes build process:

• Extensions:

  blender --command extension build

• Add-ons: Package files for installation
• Custom: Runs specified script

Step 4: Remove old version

Cleans previous installation to prevent conflicts.

Step 5: Install

Installs fresh build into Blender.

Step 6: Enable

Activates extension/add-on in Blender preferences.

Step 7: Launch

Opens Blender with your code ready to use.

Step 8: Verify

Checks console output for:

• Registration success
• Import errors
• Runtime warnings

Configuration

Create

.bgorc

in project root for persistent settings:

{
  "type": "extension",
  "extension_id": "my_extension",
  "source_dir": ".",
  "output_dir": "./build",
  "build_script": null,
  "blender_path": "blender",
  "launch_args": ["--log", "*", "--log-level", "1"],
  "auto_validate": true,
  "clean_build": false,
  "auto_screenshot": false
}

Configuration fields:

• type

  : "extension" or "addon"

• extension_id

  /

  module

  : Extension ID or add-on module name

• source_dir

  : Path to source code

• output_dir

  : Build output directory

• build_script

  : Custom build script path (optional)

• blender_path

  : Path to Blender executable (default: system PATH)

• launch_args

  : Additional arguments for Blender launch

• auto_validate

  : Run validation before build (default: true)

• clean_build

  : Remove build directory before building (default: false)

• auto_screenshot

  : Capture viewport screenshot after launch (default: false)

Integration with Other Skills

Works seamlessly with:

• blender-extension-dev

  : Uses build/install scripts

• blender-addon-testing

  : Runs tests after build (with

  --test

  flag)

• blender-use

  : Can capture screenshots after launch for verification

Example combined workflow:

# Build, install, test, and launch
/bgo --test --auto-screenshot

# This executes:
# 1. Build extension
# 2. Install extension
# 3. Run test suite (from blender-addon-testing)
# 4. Launch Blender
# 5. Capture screenshot (from blender-use)

Custom Build Scripts

If using

--script

, your script should:

1. Accept command-line arguments:

   import argparse
   parser = argparse.ArgumentParser()
   parser.add_argument('--source-dir', required=True)
   parser.add_argument('--output-dir', required=True)
   args = parser.parse_args()
   

2. Perform build operations:

   • Package files
   • Copy dependencies
   • Generate manifests
   • Run pre-processors

3. Output package to

   --output-dir

   :
   • Extensions:

     <extension_id>.zip

   • Add-ons:

     <module_name>.py

     or

     <module_name>/

     directory

4. Exit with code 0 on success, 1 on failure

Example custom script:

#!/usr/bin/env python3
import argparse
import shutil
from pathlib import Path

def build_extension(source_dir, output_dir):
    """Custom build logic"""
    source = Path(source_dir)
    output = Path(output_dir)
    output.mkdir(exist_ok=True)

    # Custom preprocessing
    print("Running custom build steps...")

    # Use Blender's build command
    import subprocess
    subprocess.run([
        "blender", "--command", "extension", "build",
        "--source-dir", str(source),
        "--output-dir", str(output)
    ], check=True)

    print(f"Build complete: {output}")

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument('--source-dir', required=True)
    parser.add_argument('--output-dir', required=True)
    args = parser.parse_args()

    build_extension(args.source_dir, args.output_dir)

Troubleshooting

Build fails:

• Check manifest validation output
• Verify source files exist
• Review custom script errors (if using

  --script

  )
• Check Blender version compatibility

Remove fails:

• Extension/add-on may not be installed (non-fatal, continues)
• Check extension ID or module name is correct
• Verify Blender can access preferences

Install fails:

• Build output not found in

  --output-dir

• Incorrect package format
• Blender version mismatch
• File permission issues

Enable fails:

• Extension/add-on has registration errors
• Missing dependencies
• Incompatible Blender version
• Check Blender console for Python errors

Launch fails:

• Blender not in system PATH (use

  --blender-path

  )
• Blender executable name different on your system
• Permission issues

Extension/add-on doesn't appear:

• Check Blender console for import errors
• Verify enabled in Preferences → Add-ons/Extensions
• Look for registration errors in console
• Try manual enable: Edit → Preferences → Add-ons

Advanced Usage

Pre-launch validation

/bgo --validate-only

Runs build and validation without installing or launching. Useful for CI/CD.

Silent mode (CI/CD)

/bgo --headless --no-launch --exit-code

Returns exit code based on success/failure. No interactive prompts.

With test execution

/bgo --test --test-dir ./tests --report-format json

Runs test suite after installation, before launching Blender.

Custom Blender version

/bgo --blender-path /path/to/blender-4.2/blender

Use specific Blender version for testing.

Best Practices

Use

.bgorc

for projects: Set up configuration once, then just run

/bgo

.

Clean builds for releases: Use

--clean

before release builds to ensure no stale artifacts.

Test before launch: Add

--test

to catch errors before manual testing.

Auto-screenshot: Enable

auto_screenshot

in

.bgorc

to capture viewport state after launch for documentation.

Version control: Add

build/

to

.gitignore

, commit

.bgorc

for team consistency.

CI/CD integration: Use

--headless --no-launch --exit-code

in automated pipelines.

Examples

Basic development iteration:

# Edit code...
/bgo
# Blender opens with changes loaded

Release build:

/bgo --clean --validate-only
# Review validation results
/bgo --clean
# Blender opens with clean build

Multi-version testing:

/bgo --blender-path /path/to/blender-4.2/blender
/bgo --blender-path /path/to/blender-4.3/blender

Full validation pipeline:

/bgo --clean --test --test-dir ./tests --auto-screenshot --launch-args "--log * --log-level 0"

Output and Logs

/bgo

outputs progress to console:

[bgo] Detecting project type...
[bgo] ✓ Found extension manifest: my_extension
[bgo] Validating manifest...
[bgo] ✓ Manifest valid
[bgo] Building extension...
[bgo] ✓ Built: build/my_extension.zip
[bgo] Removing old version...
[bgo] ✓ Removed: my_extension
[bgo] Installing extension...
[bgo] ✓ Installed: my_extension
[bgo] Enabling extension...
[bgo] ✓ Enabled: my_extension
[bgo] Launching Blender...
[bgo] ✓ Blender started (PID: 12345)
[bgo] Verifying load...
[bgo] ✓ Extension loaded successfully
[bgo] Done! Blender is ready.

Log files:

• build/bgo.log

  : Full execution log

• build/blender_console.log

  : Blender console output (if

  --capture-logs

  )

Comparison with Manual Workflow

Manual workflow:

# 1. Build
blender --command extension build --source-dir . --output-dir build/

# 2. Remove old
blender --command extension remove my_extension

# 3. Install
blender --command extension install-file build/my_extension.zip

# 4. Launch
blender

# 5. Enable manually in UI
# Edit → Preferences → Extensions → Enable my_extension

With

/bgo

:

/bgo

Time saved: ~2-3 minutes per iteration × many iterations = significant productivity boost.