Headless / CI Mode

Blueprint AI does not require the Unreal Editor to be running. Every operation runs through a Python commandlet that launches a short-lived headless editor instance, performs the mutation, writes results, and exits. You can drive the whole stack from:

• An external IDE talking to a local CLI
• A CI job that runs validations on pull requests
• A build server preparing a content snapshot
• Any AI tool that can shell out

The in-editor chat panel is a convenience surface — it’s not a requirement.

How it works

When you (or your AI assistant) invoke cli.py apply:

$  python cli.py apply spec.json
       │
       ▼
   Validate JSON against the operations schema
       │
       ▼
   Resolve dependencies, batch order
       │
       ▼
   Generate Python that calls UE editor APIs
       │
       ▼
   Launch UE in commandlet mode (no window)
       │
       ▼
   Run the Python in-process inside the engine
       │
       ▼
   Engine exits; result JSON printed to stdout

Cold-start cost for a commandlet is around 5–10 seconds on a typical workstation. For batches the cost amortizes: the same commandlet runs the whole batch in one boot.

A round trip from an IDE chat assistant looks the same way the in-editor panel works — the AI emits JSON ops, the CLI runs them, the diagnostic is fed back to the AI. There is no second protocol.

Driving from an IDE

Most modern IDEs let you wire up a CLI as a tool. The general pattern:

1. Tell the AI to use the operations schema (a one-line skill reference works for Claude, custom-tool definitions for others)
2. The AI emits JSON, the IDE pipes it to cli.py apply --stdin
3. The CLI returns the result, the AI sees it, iterates

Claude (any client)

The skill auto-installs at ~/.claude/skills/unreal/. Any Claude client picks it up — including the Claude Desktop app, the Claude VS Code extension, claude in a terminal, or the Claude SDK in your own scripts. No additional setup beyond opening the editor once.

Claude is the supported assistant with a bundled skill. Auto-install for Cursor, GitHub Copilot, Windsurf, and OpenAI Codex ships next.

Bring-your-own

Any CLI-capable assistant works. Point it at the CLI and let the self-documenting schema do the rest:

# Discover what's available
python cli.py schema

# Apply a JSON plan
echo '{"op":"create_blueprint","name":"BP_Pickup","path":"/Game/Pickups"}' \
    | python cli.py apply --stdin

# Inspect existing assets
python cli.py describe --asset /Game/Pickups/BP_Pickup

The schema is self-describing — your AI only needs to be told once that cli.py schema exists; everything else follows from the JSON it returns.

CI usage

In a build server context:

.github/workflows/blueprints.yml

- name: Apply blueprint plan
  run: |
    python Plugins/BlueprintAI/Scripts/cli.py apply Plans/initial.json
  env:
    UE_INSTALL_DIR: ${{ env.UE_INSTALL_DIR }}

The CLI exits non-zero on any failure with a parseable diagnostic on stderr — wire it into your usual failure path.

For pull-request validation:

# Type-check every plan in Plans/ without executing
python cli.py validate Plans/*.json

validate runs the schema check, dependency resolution, and codegen without launching the engine, so it’s fast (milliseconds, not seconds) and safe to run on every push.

Working directory

The CLI honors AgentWorkingDirectory from Project Settings when present, falling back to the project root. This matters in monorepos where the .uproject lives in a subfolder.

Override at the command line:

python cli.py apply spec.json --cwd path/to/project

Engine discovery

The CLI finds your engine in this order:

1. UE_INSTALL_DIR environment variable
2. The .uproject’s EngineAssociation field, resolved against the launcher’s install registry
3. Standard install paths (C:\Program Files\Epic Games\UE_5.7\ on Windows, /Users/Shared/Epic Games/UE_5.7/ on macOS, ~/UnrealEngine/ on Linux)
4. PATH scan for UnrealEditor / UnrealEditor.exe

You can override the discovery on any command:

python cli.py apply spec.json --engine "C:/Program Files/Epic Games/UE_5.7"

Performance notes

For a single operation, prefer batching over many small commandlets:

// Slow — three commandlet boots
{"op":"create_blueprint", "name":"BP_A"}
{"op":"create_blueprint", "name":"BP_B"}
{"op":"create_blueprint", "name":"BP_C"}

// Fast — one boot, three ops
{"ops":[
  {"op":"create_blueprint", "name":"BP_A"},
  {"op":"create_blueprint", "name":"BP_B"},
  {"op":"create_blueprint", "name":"BP_C"}
]}

The CLI does this automatically when you apply an array; the AI’s skill knows to batch related ops.

For continuous workflows (e.g., a live agent iterating quickly), keep the editor open with the panel — the editor’s already-loaded asset registry skips the cold start entirely. You don’t need to interact with the editor; just leave it running.

When you do need the editor open

A handful of operations need a real editor session for sub-systems that don’t initialize in commandlet mode (some PIE-specific assets, certain niagara workflows). The CLI detects this and prints a clear “this op needs an open editor” diagnostic instead of failing silently.

Logs and diagnostics

Every commandlet run writes a log to:

<Project>/Saved/Logs/BlueprintAI-cli-<timestamp>.log

Recent runs are retained for 7 days. The CLI’s stdout includes the path on every failure so you can grep without hunting.

For verbose tracing of the AI side, pipe the chat client’s stderr to a file — Claude respects CLAUDE_LOG_FILE.