cli-anything-blender

A stateful command-line interface for 3D scene editing, following the same patterns as the GIMP CLI harness. Uses a JSON scene description format with bpy script generation for actual Blender rendering.

Installation

This CLI is installed as part of the cli-anything-blender package:

pip install cli-anything-blender

Prerequisites:

• Python 3.10+
• blender (>= 4.2) must be installed on your system

Usage

Basic Commands

# Show help
cli-anything-blender --help

# Start interactive REPL mode
cli-anything-blender

# Create a new scene project
cli-anything-blender scene new -o scene.blend-cli.json

# Run with JSON output (for agent consumption)
cli-anything-blender --json --project scene.blend-cli.json scene info

REPL Mode

When invoked without a subcommand, the CLI enters an interactive REPL session:

cli-anything-blender
# Enter commands interactively with tab-completion and history

Command Groups

Scene

Scene management commands.

Command	Description
new	Create a new scene
open	Open an existing scene
save	Save the current scene
info	Show scene information
profiles	List available scene profiles
json	Print raw scene JSON

Object Group

3D object management commands.

Command	Description
add	Add a 3D primitive object
remove	Remove an object by index
duplicate	Duplicate an object
transform	Transform an object (translate, rotate, scale)
set	Set an object property (name, visible, location, rotation, scale, parent)
list	List all objects
get	Get detailed info about an object

Material

Material management commands.

Command	Description
create	Create a new material
assign	Assign a material to an object
set	Set a material property (color, metallic, roughness, specular, alpha, etc.)
list	List all materials
get	Get detailed info about a material

Modifier Group

Modifier management commands.

Command	Description
list-available	List all available modifiers
info	Show details about a modifier
add	Add a modifier to an object
remove	Remove a modifier by index
set	Set a modifier parameter
list	List modifiers on an object

Camera

Camera management commands.

Command	Description
add	Add a camera to the scene
set	Set a camera property
set-active	Set the active camera
list	List all cameras

Light

Light management commands.

Command	Description
add	Add a light to the scene
set	Set a light property
list	List all lights

Animation

Animation and keyframe commands.

Command	Description
keyframe	Set a keyframe on an object
remove-keyframe	Remove a keyframe from an object
frame-range	Set the animation frame range
fps	Set the animation FPS
list-keyframes	List keyframes for an object

Render Group

Render settings and output commands.

Command	Description
settings	Configure render settings
info	Show current render settings
presets	List available render presets
execute	Render the scene (generates bpy script)
script	Generate bpy script without rendering

Preview

Real preview bundle capture and live preview session commands.

Command	Description
preview recipes	List available preview recipes
preview capture	Render a real preview bundle for the active scene
preview latest	Return the latest existing preview bundle
preview live start	Start a live preview session and publish the first bundle
preview live push	Publish a refreshed bundle into the live session
preview live status	Read current live-session state without rendering
preview live stop	Stop the live session without deleting artifacts

Typical bundle artifacts for recipe quick:

• hero.png from real Eevee preview rendering
• workbench.png from real Blender Workbench rendering

Live sessions persist:

• session.json as the mutable head
• immutable bundle directories
• trajectory.json as append-only command-to-preview history

Viewer side:

• cli-hub previews inspect <bundle-or-session>
• cli-hub previews html <bundle-or-session> -o page.html
• cli-hub previews watch <session-dir> --open
• cli-hub previews open <bundle-or-session>

Session

Session management commands.

Command	Description
status	Show session status
undo	Undo the last operation
redo	Redo the last undone operation
history	Show undo history

Examples

Create a New Project

Create a new Blender scene project file.

cli-anything-blender scene new -o myscene.blend-cli.json
# Or with JSON output for programmatic use
cli-anything-blender --json scene new -o myscene.blend-cli.json

Interactive REPL Session

Start an interactive session with undo/redo support.

cli-anything-blender
# Enter commands interactively
# Use 'help' to see available commands
# Use 'undo' and 'redo' for history navigation

State Management

The CLI maintains session state with:

• Undo/Redo: Up to 50 levels of history
• Project persistence: Save/load project state as JSON
• Session tracking: Track modifications and changes

Output Formats

All commands support dual output modes:

• Human-readable (default): Tables, colors, formatted text
• Machine-readable (--json flag): Structured JSON for agent consumption

# Human output
cli-anything-blender --project scene.blend-cli.json scene info

# JSON output for agents
cli-anything-blender --json --project scene.blend-cli.json scene info

Preview Workflow

Use Blender previews when the agent needs truthful visual checkpoints:

# List preview recipes
cli-anything-blender --project scene.blend-cli.json preview recipes

# Capture a real preview bundle
cli-anything-blender --json --project scene.blend-cli.json preview capture --recipe quick

# Start a live preview loop
cli-anything-blender --json --project scene.blend-cli.json preview live start --recipe quick --mode poll --source-poll-ms 500

# Query current live head without rendering
cli-anything-blender --json --project scene.blend-cli.json preview live status --recipe quick

For agents, preview capture --json returns bundle metadata plus artifact file paths. preview live status --json returns session metadata plus a compact trajectory_summary.

For AI Agents

When using this CLI programmatically:

1. Always use --json flag for parseable output
2. Check return codes - 0 for success, non-zero for errors
3. Parse stderr for error messages on failure
4. MANDATORY: Use absolute paths for all file operations (rendering, project files). Relative paths are prone to failure in background execution.
5. Use preview capture or preview live ... for visual verification instead of inferring scene quality from JSON alone
6. Read returned artifact paths such as hero.png and workbench.png; the JSON payload references files, it does not inline image bytes
7. Treat _bundle_dir as one snapshot only; for stable live history, use _session_dir plus _trajectory_path
8. Use cli-hub previews ... only to inspect/open existing previews; preview generation itself always happens through cli-anything-blender preview ...

More Information

• Full documentation: See README.md in the package
• Test coverage: See TEST.md in the package
• Methodology: See HARNESS.md in the cli-anything-plugin

Version

1.0.0