yb2460/cli-anything-photoshop

CLI-Anything Photoshop

Herramienta de línea de comandos para controlar Adobe Photoshop mediante la interfaz de automatización COM de Windows.

Requisitos previos

• Windows 10/11
• Adobe Photoshop 2023+ (debe tener registrada la interfaz COM)
• Python 3.10+ y el paquete pywin32

Instalación

cd photoshop-harness/agent-harness
pip install -e .

Una vez instalado, se puede usar el comando cli-anything-photoshop.

Estructura de comandos

cli-anything-photoshop [--json] [--project <ruta>] [--dry-run] <grupo-comando> <comando> [opciones]

Opciones globales

Opción	Descripción
--json	Salida en formato JSON (para que lo analice un agente de IA)
--project <ruta>	Abre o crea automáticamente el archivo PSD
--dry-run	Ejecuta el comando pero no guarda cambios en disco

Grupos de comandos

project — Gestión de proyectos

Comando	Opciones	Descripción
new <ruta>	-w ancho, -h alto, -r resolución, -m modo, -b color-fondo	Crear nuevo PSD
open <ruta>		Abrir archivo PSD
save [ruta]		Guardar documento
close	--no-save	Cerrar documento

document — Operaciones de documento

Comando	Opciones	Descripción
info		Información del documento
resize	-w ancho, -h alto, -r resolución	Cambiar tamaño
canvas	-w ancho, -h alto, -a ancla	Ajustar lienzo
crop	--left --top --right --bottom	Recortar
rotate	-a ángulo	Rotar lienzo
flip	-d dirección	Voltear lienzo
mode	-m modo	Cambiar modo de color
trim	-t tipo	Recortar bordes

layer — Manipulación de capas

Comando	Opciones	Descripción
add	-n nombre, -t tipo, -o opacidad, -b fusión	Agregar capa
delete	-n nombre	Eliminar capa
duplicate	-n nombre, --new-name nombre	Duplicar capa
rename	--old nombre, --new nombre	Renombrar
show / hide	-n nombre	Mostrar/ocultar
opacity	-n nombre, -o opacidad	Establecer opacidad
blend	-n nombre, -m modo	Establecer modo de fusión
list		Listar todas las capas
reorder	-n nombre, -p posición	Reordenar
merge	-n nombre, --with-layer nombre	Fusionar capas

selection — Operaciones de selección

Comando	Opciones	Descripción
all		Seleccionar todo
none		Cancelar selección
invert		Invertir selección
feather	-r radio	Difuminar
expand	-p píxeles	Expandir
contract	-p píxeles	Contraer
border	-w ancho	Borde de selección
rect	--left --top --right --bottom	Selección rectangular
fill	-c color, -o opacidad	Rellenar selección

text — Operaciones de texto

Comando	Opciones	Descripción
add	-t texto, -f fuente, -s tamaño, -c color	Agregar texto
edit	-n nombre, -t texto, -f fuente, -s tamaño, -c color	Editar texto
info	-n nombre	Información de texto

export — Exportación

Comando	Opciones	Descripción
save <ruta>	-f formato, -q calidad, -w ancho, -h alto	Exportar archivo

repl

Comando	Descripción
repl	Iniciar modo REPL interactivo

Ejemplos de uso

Uso con agente de IA (modo --json)

# Crear nuevo proyecto y obtener salida JSON
cli-anything-photoshop --json project new -w 800 -h 600 poster.psd

# Agregar una capa de texto
cli-anything-photoshop --json --project poster.psd text add -t "Hola Mundo" -f Arial -s 48 -c "#FF0000"

# Listar todas las capas (formato JSON)
cli-anything-photoshop --json --project poster.psd layer list

# Exportar como PNG
cli-anything-photoshop --json --project poster.psd export save -f png output.png

# Vista previa (sin guardar)
cli-anything-photoshop --dry-run --project poster.psd layer add -n "borrador" --type text

Uso manual

# Abrir PSD, editar interactivamente
cli-anything-photoshop --project trabajo.psd layer list

# Iniciar REPL
cli-anything-photoshop repl

Guía de uso para agentes

1. Usar siempre la bandera --json para obtener salida estructurada
2. Usar --dry-run para previsualizar y confirmar antes de guardar definitivamente
3. Manejo de errores: si el código de salida no es cero, revisar el stderr donde se encuentra el objeto JSON de error
4. Estado del proyecto: usar --project para manejar automáticamente apertura/guardado de archivos
5. Modo REPL: ideal para operaciones interactivas de múltiples pasos, reduce la sobrecarga de iniciar procesos de Photoshop

Arquitectura COM de Photoshop

Comando CLI → Click CLI → Módulo Core → ComBridge (singleton) → Photoshop.Application COM → Motor de Photoshop

Photoshop expone todas sus capacidades de edición a través de la interfaz COM de Windows. Este harness encapsula las operaciones más comunes. Para ampliarlo, consultar la documentación de Adobe Photoshop COM y agregar nuevos métodos en utils/com_bridge.py.