lightroom-cli 1.0.0

CLI tool for Adobe Lightroom Classic — 107 commands for full Lightroom control

Lightroom CLI

Japanese / 日本語

Full command-line control for Adobe Lightroom Classic — 107 commands.

Develop parameter adjustment, masking, tone curves, catalog management, selection operations, and more. Ideal for batch processing and scripted automation.

Architecture

+---------------------+     TCP Socket (JSON-RPC)     +--------------+
|  Lightroom Classic  |<----------------------------->|  Python SDK  |
|  (Lua Plugin)       |   Dual socket: send/receive   |              |
+---------------------+                               +------+-------+
                                                              |
                                                       +------+-------+
                                                       |   CLI (lr)   |
                                                       |   Click app  |
                                                       +--------------+

A Lua plugin runs inside Lightroom Classic and communicates with the Python SDK via dual TCP sockets (one for sending, one for receiving) using JSON-RPC. The CLI operates as the lr command and controls Lightroom through the SDK.

Quick Start

Prerequisites

• Python 3.10+
• Adobe Lightroom Classic (desktop version)
• macOS (Windows untested)

Installation

From Source (Development)

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

Via pip

pip install lightroom-cli
lr plugin install

Verify Connection

# With Lightroom Classic running
lr system ping
# -> pong

lr system status

Usage Examples

# Get currently selected photo
lr catalog get-selected

# Set develop parameters
lr develop set Exposure 1.5 Contrast 25 Clarity 30

# Apply AutoTone
lr develop auto-tone

# Apply S-curve to tone curve
lr develop curve s-curve

# Create a mask and add a brush
lr develop mask create
lr develop mask add brush

# Apply a preset
lr develop preset "Vivid Landscape"

# Rating and flag operations
lr selection set-rating 5
lr selection flag

# Search the catalog
lr catalog search "landscape" --limit 20

# JSON output
lr -o json develop get-settings

# Table output
lr -o table catalog list --limit 10

Command Groups

Group	Commands	Description
lr system	4	Connection management and status
lr catalog	27	Catalog operations, photo search, metadata
lr develop	55	Develop settings, masks, curves, filters
lr preview	4	Preview generation and info
lr selection	17	Selection, flags, ratings, labels
lr plugin	3	Plugin installation and management

For all 107 commands, see the CLI Reference.

lr system

lr system ping                # Connection test
lr system status              # Bridge status
lr system reconnect           # Force reconnect
lr system check-connection    # Detailed connection check

lr catalog

lr catalog get-selected               # Get currently selected photo
lr catalog list --limit 10            # List photos
lr catalog search "keyword"           # Search
lr catalog get-info <photo_id>        # Detailed metadata
lr catalog set-rating <id> 5          # Set rating
lr catalog add-keywords <id> kw1 kw2  # Add keywords
lr catalog set-title <id> "Title"     # Set title
lr catalog collections                # List collections
lr catalog create-collection "name"   # Create collection
lr catalog keywords                   # List keywords
lr catalog set-view-filter <json>     # Set view filter
lr catalog rotate-left                # Rotate left
lr catalog create-virtual-copy        # Create virtual copy

lr develop

# Basic operations
lr develop get-settings               # Get all develop settings
lr develop set Exposure 1.5           # Set parameter
lr develop get Exposure               # Get single parameter
lr develop auto-tone                  # AutoTone
lr develop auto-wb                    # Auto White Balance
lr develop reset                      # Reset settings
lr develop apply '{"Exposure": 1.0}'  # Apply settings from JSON

# Tone curve
lr develop curve get                  # Get curve
lr develop curve set '[[0,0],[128,140],[255,255]]'
lr develop curve s-curve              # S-curve preset
lr develop curve linear               # Linear reset
lr develop curve add-point 128 140    # Add point

# Masking
lr develop mask list                  # List all masks
lr develop mask create                # Create new mask
lr develop mask add brush             # Add brush component
lr develop mask intersect luminance   # Intersect with luminance
lr develop mask subtract color        # Subtract with color
lr develop mask invert mask-1         # Invert mask

# Filters
lr develop filter graduated           # Graduated filter
lr develop filter radial              # Radial filter
lr develop filter brush               # Brush filter
lr develop filter ai-select           # AI select

# Local adjustments
lr develop local set Exposure 0.5     # Set local parameter
lr develop local get Exposure         # Get local parameter

# Tools, presets, and snapshots
lr develop tool crop                  # Select tool
lr develop preset "Preset Name"       # Apply preset
lr develop snapshot "Snapshot Name"   # Create snapshot
lr develop copy-settings              # Copy settings
lr develop paste-settings             # Paste settings

lr preview

lr preview generate-current           # Generate preview for selected photo
lr preview generate --size 2048       # Generate with specified size
lr preview generate-batch             # Batch generation
lr preview info                       # Preview info

lr selection

lr selection flag                     # Pick flag
lr selection reject                   # Reject flag
lr selection unflag                   # Remove flag
lr selection get-flag                 # Get flag state
lr selection set-rating 5             # Set rating (0-5)
lr selection get-rating               # Get rating
lr selection color-label red          # Set color label
lr selection get-color-label          # Get color label
lr selection toggle-label red         # Toggle label
lr selection next                     # Next photo
lr selection previous                 # Previous photo
lr selection select-all               # Select all
lr selection select-none              # Deselect all
lr selection select-inverse           # Invert selection
lr selection extend --direction right # Extend selection

Global Options

lr --output json ...    # JSON output (-o json)
lr --output table ...   # Table output (-o table)
lr --verbose ...        # Debug logging (-v)
lr --timeout 60 ...     # Timeout in seconds (-t 60)
lr --version            # Show version

Configuration

Environment Variable	Description
LR_PORT_FILE	Path to the port file used for socket communication
LR_PLUGIN_DIR	Path to the Lightroom plugin directory

Features

• Auto-reconnect: Automatically retries when the Lightroom connection drops (exponential backoff)
• Heartbeat: Connection monitoring at 30-second intervals
• Shutdown detection: Graceful handling when Lightroom exits
• 3 output formats: text / json / table
• Tab completion: Completion support for develop parameter names
• Per-command timeout: Long-running operations like preview generation are automatically extended

Development

# Install for development
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

# With coverage
python -m pytest tests/ -v --cov=lightroom_sdk --cov=cli

# Single test file
python -m pytest tests/integration/test_cli_develop.py -v

Project Structure

lightroom-cli/
+-- cli/                      # Click CLI application
|   +-- main.py               # Entry point (lr command)
|   +-- output.py             # OutputFormatter (json/text/table)
|   +-- helpers.py            # bridge_command decorator
|   +-- completions.py        # Tab completion
|   +-- commands/             # Command groups
|       +-- system.py         # lr system
|       +-- catalog.py        # lr catalog
|       +-- develop.py        # lr develop (+ curve/mask/local/filter/debug/color)
|       +-- preview.py        # lr preview
|       +-- selection.py      # lr selection
|       +-- plugin.py         # lr plugin
+-- lightroom_sdk/            # Python SDK
|   +-- client.py             # LightroomClient
|   +-- socket_bridge.py      # Dual TCP socket
|   +-- resilient_bridge.py   # Auto-reconnect + heartbeat
|   +-- retry.py              # Per-command timeout
|   +-- protocol.py           # JSON-RPC protocol
|   +-- paths.py              # Path resolution utilities
|   +-- plugin/               # Lua plugin (bundled)
|       +-- PluginInit.lua    # Command router (107 commands)
|       +-- DevelopModule.lua # Develop operations
|       +-- CatalogModule.lua # Catalog operations
+-- tests/                    # pytest test suite (680+ tests)

Requirements

• Python >= 3.10
• Adobe Lightroom Classic
• macOS (Windows untested)

Python Dependencies

• click >= 8.1 — CLI framework
• rich >= 13.0 — Table output
• pydantic >= 2.0 — Data validation
• platformdirs >= 3.0 — Platform-specific directory paths

License

MIT