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)
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"
cli-anything-photoshop --json --project poster.psd layer list
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
Human Usage
cli-anything-photoshop --project work.psd layer list
cli-anything-photoshop repl
Agent Usage Guide
- Always use the
--json flag for structured output
- Use
--dry-run to preview before committing to a save
- Error handling: Check
stderr for JSON error objects when exit code is non-zero
- Project state: 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 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.