photoshop-cli

photoshop-cli

Japanese / 日本語

Control Adobe Photoshop from the command line via AI agents.

Open, close, save PSD files, inspect document info, and automate Photoshop workflows through CLI or MCP server.

Architecture

+---------------------+     WebSocket      +---------------+
|  Adobe Photoshop    |<------------------->|  Python SDK   |
|  (UXP Plugin)       |  WS Client → Server |               |
+---------------------+                    +-------+-------+
                                                   |
                                     +-------------+-------------+
                                     |             |             |
                              +------+------+ +----+-------+ +---+--------+
                              |  CLI (psd)  | | MCP Server | | Python SDK |
                              |  Click app  | | (psd-mcp)  | |   Direct   |
                              +-------------+ +------------+ +------------+

A UXP plugin runs inside Photoshop and connects as a WebSocket client to the Python SDK server. Three interfaces are available: the psd CLI, the MCP Server for Claude Desktop/Cowork, and the Python SDK for direct integration.

Quick Start

Prerequisites

• Python 3.10+
• Adobe Photoshop (with UXP Plugin support)
• macOS (Windows support planned)

Installation

From PyPI

pip install photoshop-cli

From Source

git clone https://github.com/znznzna/photoshop-cli.git
cd photoshop-cli
pip install -e ".[dev]"

UXP Plugin Setup

1. Open UXP Developer Tool (UDT)
2. Load the plugin from uxp-plugin/ directory
3. Enable the plugin in Photoshop

Choose Your Integration

Option A: Claude Code (SKILL-based)

For Claude Code users — install the Claude Code Plugin:

/plugin marketplace add znznzna/photoshop-cli
/plugin install photoshop-cli@photoshop-cli

The agent reads SKILL.md to discover available commands. No manual typing needed.

Option B: Claude Desktop / Cowork (MCP Server)

For Claude Desktop or Cowork users — register the MCP Server:

psd mcp install

Restart Claude Desktop / Cowork. Commands are available as MCP tools with psd_ prefix.

Check MCP status:

psd mcp status
psd mcp test      # Test connection to Photoshop

Option C: Direct CLI / Scripting

Use the psd command directly:

psd system ping
psd --output json file list
psd --output json file open /path/to/file.psd

Verify Connection

1. Open Photoshop
2. Ensure the UXP Plugin is loaded and active
3. Run:

psd system ping
# -> pong

CLI Reference

File Operations

psd --output json file list                          # List open documents
psd --output json file info --doc-id <ID>            # Get document info
psd --output json file open /path/to/file.psd        # Open file
psd --output json file close --doc-id <ID>           # Close document
psd --output json file close --doc-id <ID> --save    # Save and close
psd --output json file save --doc-id <ID>            # Save document

System Operations

psd --output json system ping                        # Check connection

Schema Introspection

psd --output json schema                             # List all commands
psd --output json schema file.open                   # Show schema for file.open

MCP Server Management

psd mcp install                # Install MCP server to Claude Desktop
psd mcp install --force        # Overwrite existing entry
psd mcp uninstall              # Remove MCP server entry
psd mcp status                 # Show installation status
psd mcp test                   # Test connection via MCP

Global Options

psd --output json ...    # JSON output (-o json)
psd --output table ...   # Table output (-o table)
psd --verbose ...        # Debug logging (-v)
psd --timeout 60 ...     # Timeout in seconds (-t 60)
psd --dry-run ...        # Validate only, do not execute
psd --fields f1,f2 ...   # Filter output fields (-f f1,f2)
psd --version            # Show version

Configuration

Environment Variable	Description
PS_PORT_FILE	Path to the WebSocket port file (default: /tmp/photoshop_ws_port.txt)
PS_VERBOSE	Enable verbose logging

Features