yb2460/cli-anything-photoshop

CLI-Anything Photoshop

A command-line tool for controlling Adobe Photoshop via the Windows COM automation interface.

Prerequisites

• Windows 10/11
• Adobe Photoshop 2023+ (COM interface must be registered)
• Python 3.10+ and the 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	Options	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	Options	Description
info		Document info
resize	-w width, -h height, -r resolution	Resize dimensions
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	Options	Description
add	-n name, -t type, -o opacity, -b blend	Add a layer
delete	-n name	Delete a layer
duplicate	-n name, --new-name name	Duplicate a 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 blend mode
list		List all layers
reorder	-n name, -p position	Reorder
merge	-n name, --with-layer name	Merge layers

selection — Selection Operations

Command	Options	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	Options	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 info

export — Export

Command	Options	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)

# Create a new project and get JSON output
cli-anything-photoshop --json project new -w 800 -h 600 poster.psd

# Add a text layer
cli-anything-photoshop --json --project poster.psd text add -t "Hello World" -f Arial -s 48 -c "#FF0000"

# List all layers (JSON format)
cli-anything-photoshop --json --project poster.psd layer list

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

# Preview (without saving)
cli-anything-photoshop --dry-run --project poster.psd layer add -n "draft" --type text

Human Usage

# Open a PSD, interactive editing
cli-anything-photoshop --project work.psd layer list

# Start REPL
cli-anything-photoshop repl

Agent Usage Guide

1. Always use the --json flag for structured output
2. Use --dry-run to preview before committing to a save
3. Error handling: Check stderr for JSON error objects when exit code is non-zero
4. Project state: Use --project to automatically manage file open/save
5. REPL mode: Suitable for multi-step interactive operations, reducing Photoshop process startup overhead

Photoshop COM Architecture

CLI command → Click CLI → Core module → ComBridge (singleton) → Photoshop.Application COM → Photoshop engine

Photoshop exposes its full editing capabilities through the Windows COM interface. This harness wraps the most commonly used operations. To extend, refer to the Adobe Photoshop COM documentation and add new methods to utils/com_bridge.py.