cli-anything-photoshop

CLI-Anything Photoshop

Command-line tool for automating Adobe Photoshop through the Windows COM automation interface.

Prerequisites

Windows 10/11
Adobe Photoshop 2023+ (COM interface registration required)
Python 3.10+ and pywin32 package

Installation

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

After installation, you can use the cli-anything-photoshop command.

Command Structure

cli-anything-photoshop [--json] [--project <path>] [--dry-run] <command-group> <command> [options]

Global Options

Option	Description
`--json`	Output in JSON format (for AI Agent parsing)
`--project <path>`	Automatically open or create a PSD project file
`--dry-run`	Execute the command without saving to disk

Command Groups

project — Project Management

Command	Option	Description
`new <path>`	`-w` width, `-h` height, `-r` resolution, `-m` mode, `-b` bg-color	Create a new PSD
`open <path>`		Open a PSD file
`save [path]`		Save the document
`close`	`--no-save`	Close the document

document — Document Operations

Command	Option	Description
`info`		Document information
`resize`	`-w` width, `-h` height, `-r` resolution	Resize
`canvas`	`-w` width, `-h` height, `-a` anchor	Resize canvas
`crop`	`--left --top --right --bottom`	Crop
`rotate`	`-a` angle	Rotate canvas
`flip`	`-d` direction	Flip canvas
`mode`	`-m` mode	Change color mode
`trim`	`-t` type	Trim edges

layer — Layer Operations

Command	Option	Description
`add`	`-n` name, `-t` type, `-o` opacity, `-b` blend	Add layer
`delete`	`-n` name	Delete layer
`duplicate`	`-n` name, `--new-name` name	Duplicate layer
`rename`	`--old` name, `--new` name	Rename
`show` / `hide`	`-n` name	Show/Hide
`opacity`	`-n` name, `-o` opacity	Set opacity
`blend`	`-n` name, `-m` mode	Set blending mode
`list`		List all layers
`reorder`	`-n` name, `-p` position	Reorder
`merge`	`-n` name, `--with-layer` name	Merge layers

selection — Selection Operations

Command	Option	Description
`all`		Select all
`none`		Deselect
`invert`		Invert selection
`feather`	`-r` radius	Feather
`expand`	`-p` pixels	Expand
`contract`	`-p` pixels	Contract
`border`	`-w` width	Border selection
`rect`	`--left --top --right --bottom`	Rectangular selection
`fill`	`-c` color, `-o` opacity	Fill selection

text — Text Operations

Command	Option	Description
`add`	`-t` text, `-f` font, `-s` size, `-c` color	Add text
`edit`	`-n` name, `-t` text, `-f` font, `-s` size, `-c` color	Edit text
`info`	`-n` name	Text information

export — Export

Command	Option	Description
`save <path>`	`-f` format, `-q` quality, `-w` width, `-h` height	Export file

repl

Command	Description
`repl`	Start interactive REPL mode

Usage Examples

AI Agent Usage (--json mode)

# 创建新项目并获取 JSON 输出
cli-anything-photoshop --json project new -w 800 -h 600 poster.psd

# 添加文字图层
cli-anything-photoshop --json --project poster.psd text add -t "Hello World" -f Arial -s 48 -c "#FF0000"

# 列出所有图层（JSON 格式）
cli-anything-photoshop --json --project poster.psd layer list

# 导出为 PNG
cli-anything-photoshop --json --project poster.psd export save -f png output.png

# 预览（不保存）
cli-anything-photoshop --dry-run --project poster.psd layer add -n "draft" --type text

Manual Usage

# 打开 PSD，交互编辑
cli-anything-photoshop --project work.psd layer list

# 启动 REPL
cli-anything-photoshop repl

Agent Usage Guide

Always use the --json flag to get structured output
Use --dry-run to preview, and save officially after confirmation
Error Handling: when the exit code is non-zero, check the JSON error object in stderr JSON error object in
Project Status: Use --project to automatically manage file open/save
REPL mode: suitable for multi-step interactive operations, reducing Photoshop process startup overhead

Photoshop COM architecture

CLI 命令 → Click CLI → Core 模块 → ComBridge (单例) → Photoshop.Application COM → Photoshop 引擎

Photoshop exposes all editing capabilities through the Windows COM interface. This harness encapsulates the most commonly used operations. To extend it, refer to the Adobe Photoshop COM documentation to add new methods to utils/com_bridge.py。