cli-anything-blender

O que cli-anything-blender faz?

Uma interface de linha de comando com estado para edição de cenas 3D, seguindo os mesmos padrões do harness CLI do GIMP. Utiliza um formato JSON de descrição de cena com geração de scripts bpy para renderização real no Blender.

Instalação

Este CLI é instalado como parte do pacote cli-anything-blender:

pip install cli-anything-blender

Pré-requisitos:

• Python 3.10+
• blender (>= 4.2) deve estar instalado no seu sistema

Uso

Comandos Básicos

# Exibir ajuda
cli-anything-blender --help

# Iniciar modo interativo REPL
cli-anything-blender

# Criar um novo projeto de cena
cli-anything-blender scene new -o scene.blend-cli.json

# Executar com saída JSON (para consumo por agentes)
cli-anything-blender --json --project scene.blend-cli.json scene info

Modo REPL

Quando invocado sem um subcomando, o CLI entra em uma sessão interativa REPL:

cli-anything-blender
# Digite comandos interativamente com preenchimento por tab e histórico

Grupos de Comandos

Cena

Comandos de gerenciamento de cena.

Comando	Descrição
new	Criar uma nova cena
open	Abrir uma cena existente
save	Salvar a cena atual
info	Mostrar informações da cena
profiles	Listar perfis de cena disponíveis
json	Imprimir o JSON bruto da cena

Grupo Objeto

Comandos de gerenciamento de objetos 3D.

Comando	Descrição
add	Adicionar um objeto primitivo 3D
remove	Remover um objeto pelo índice
duplicate	Duplicar um objeto
transform	Transformar um objeto (translatar, rotacionar, escalar)
set	Definir uma propriedade do objeto (nome, visível, localização, rotação, escala, pai)
list	Listar todos os objetos
get	Obter informações detalhadas sobre um objeto

Material

Comandos de gerenciamento de materiais.

Comando	Descrição
create	Criar um novo material
assign	Atribuir um material a um objeto
set	Definir uma propriedade do material (cor, metálico, rugosidade, especular, alfa, etc.)
list	Listar todos os materiais
get	Obter informações detalhadas sobre um material

Grupo Modificador

Comandos de gerenciamento de modificadores.

Comando	Descrição
list-available	Listar todos os modificadores disponíveis
info	Mostrar detalhes sobre um modificador
add	Adicionar um modificador a um objeto
remove	Remover um modificador pelo índice
set	Definir um parâmetro do modificador
list	Listar modificadores em um objeto

Câmera

Comandos de gerenciamento de câmeras.

Comando	Descrição
add	Adicionar uma câmera à cena
set	Definir uma propriedade da câmera
set-active	Definir a câmera ativa
list	Listar todas as câmeras

Luz

Comandos de gerenciamento de luzes.

Comando	Descrição
add	Adicionar uma luz à cena
set	Definir uma propriedade da luz
list	Listar todas as luzes

Animação

Comandos de animação e quadros-chave.

Comando	Descrição
keyframe	Definir um quadro-chave em um objeto
remove-keyframe	Remover um quadro-chave de um objeto
frame-range	Definir o intervalo de quadros da animação
fps	Definir os FPS da animação
list-keyframes	Listar quadros-chave para um objeto

Grupo Renderização

Comandos de configuração e saída de renderização.

Comando	Descrição
settings	Configurar as definições de renderização
info	Mostrar as definições de renderização atuais
presets	Listar predefinições de renderização disponíveis
execute	Renderizar a cena (gera script bpy)
script	Gerar script bpy sem renderizar

Preview

Comandos de captura de bundle de preview em tempo real e sessão ao vivo.

Comando	Descrição
preview recipes	Listar receitas de preview disponíveis
preview capture	Renderizar um bundle de preview real para a cena ativa
preview latest	Retornar o bundle de preview existente mais recente
preview live start	Iniciar uma sessão de preview ao vivo e publicar o primeiro bundle
preview live push	Publicar um bundle atualizado na sessão ao vivo
preview live status	Ler o estado atual da sessão ao vivo sem renderizar
preview live stop	Parar a sessão ao vivo sem excluir artefatos

Artefatos típicos de bundle para a receita quick:

• hero.png da renderização de preview real do Eevee
• workbench.png da renderização real do Blender Workbench

Sessões ao vivo persistem:

• session.json como o cabeçalho mutável
• diretórios de bundle imutáveis
• trajectory.json como histórico de comando-para-preview somente anexação

Lado do visualizador:

• cli-hub previews inspect <bundle-ou-sessao>
• cli-hub previews html <bundle-ou-sessao> -o pagina.html
• cli-hub previews watch <diretorio-da-sessao> --open
• cli-hub previews open <bundle-ou-sessao>

Sessão

Comandos de gerenciamento de sessão.

Comando	Descrição
status	Mostrar o status da sessão
undo	Desfazer a última operação
redo	Refazer a última operação desfeita
history	Mostrar o histórico de desfazer

Exemplos

Criar um Novo Projeto

Crie um arquivo de projeto de cena do Blender.

cli-anything-blender scene new -o minha-cena.blend-cli.json
# Ou com saída JSON para uso programático
cli-anything-blender --json scene new -o minha-cena.blend-cli.json

Sessão Interativa REPL

Inicie uma sessão interativa com suporte a desfazer/refazer.

cli-anything-blender
# Digite comandos interativamente
# Use 'help' para ver os comandos disponíveis
# Use 'undo' e 'redo' para navegação no histórico

Gerenciamento de Estado

O CLI mantém o estado da sessão com:

• Desfazer/Refazer: Até 50 níveis de histórico
• Persistência de projeto: Salvar/carregar estado do projeto como JSON
• Rastreamento de sessão: Rastrear modificações e mudanças

Formatos de Saída

Todos os comandos suportam modos de saída duplos:

• Legível por humanos (padrão): Tabelas, cores, texto formatado
• Legível por máquina (flag --json): JSON estruturado para consumo por agentes

# Saída humana
cli-anything-blender --project cena.blend-cli.json scene info

# Saída JSON para agentes
cli-anything-blender --json --project cena.blend-cli.json scene info

Fluxo de Preview

Use previews do Blender quando o agente precisar de pontos de verificação visuais verdadeiros:

# Listar receitas de preview
cli-anything-blender --project cena.blend-cli.json preview recipes

# Capturar um bundle de preview real
cli-anything-blender --json --project cena.blend-cli.json preview capture --recipe quick

# Iniciar um loop de preview ao vivo
cli-anything-blender --json --project cena.blend-cli.json preview live start --recipe quick --mode poll --source-poll-ms 500

# Consultar o cabeçalho atual ao vivo sem renderizar
cli-anything-blender --json --project cena.blend-cli.json preview live status --recipe quick

Para agentes, preview capture --json retorna metadados do bundle mais caminhos de arquivos de artefatos. preview live status --json retorna metadados da sessão mais um trajectory_summary compacto.

Para Agentes de IA

Ao usar este CLI programaticamente:

1. Sempre use a flag --json para saída analisável
2. Verifique os códigos de retorno - 0 para sucesso, diferente de zero para erros
3. Analise o stderr para mensagens de erro em caso de falha
4. OBRIGATÓRIO: Use caminhos absolutos para todas as operações de arquivo (renderização, arquivos de projeto). Caminhos relativos são propensos a falhas em execução em segundo plano.
5. Use preview capture ou preview live ... para verificação visual em vez de inferir a qualidade da cena apenas a partir do JSON
6. Leia os caminhos dos artefatos retornados, como hero.png e workbench.png; a carga JSON referencia arquivos, não incorpora bytes de imagem
7. Trate _bundle_dir como apenas um instantâneo; para um histórico ao vivo estável, use _session_dir mais _trajectory_path
8. Use cli-hub previews ... apenas para inspecionar/abrir previews existentes; a geração de preview em si sempre ocorre através de cli-anything-blender preview ...

Mais Informações

• Documentação completa: Consulte README.md no pacote
• Cobertura de testes: Consulte TEST.md no pacote
• Metodologia: Consulte HARNESS.md no plugin cli-anything

Versão

1.0.0