Skip to content
Skills Library
Personal productivity · Automation

lightroom-cli

/lightroom-cli

Control Adobe Lightroom Classic via CLI. Use when the user wants to interact with Lightroom — adjust develop settings, manage catalog, navigate photos, apply presets, or automate photo workflows. Triggers: "Lightroomで", "現像設定を", "写真を編集", "カタログから", "lr コマンド", "プリセットを適用", "写真の露出", "ホワイトバランス", "プレビュー生成", "写真を検索". Do NOT use for general image editing unrelated to Lightroom Classic.

Licence
MIT
Last repository change
03.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 03.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Control Adobe Lightroom Classic via CLI. Use when the user wants to interact with Lightroom — adjust develop settings, manage catalog, navigate photos, apply presets, or automate photo workflows. Triggers: "Lightroomで", "現像設定を", "写真を編集", "カタログから", "lr コマンド", "プリセットを適用", "写真の露出", "ホワイトバランス", "プレビュー生成", "写真を検索". Do NOT use for general image editing unrelated to Lightroom Classic.

Triggers from the description

Lightroomで現像設定を写真を編集カタログからlr コマンドプリセットを適用写真の露出ホワイトバランス
Original author description

Control Adobe Lightroom Classic via CLI. Use when the user wants to interact with Lightroom — adjust develop settings, manage catalog, navigate photos, apply presets, or automate photo workflows. Triggers: "Lightroomで", "現像設定を", "写真を編集", "カタログから", "lr コマンド", "プリセットを適用", "写真の露出", "ホワイトバランス", "プレビュー生成", "写真を検索". Do NOT use for general image editing unrelated to Lightroom Classic.

How it works

  1. Agent Quick Contract
  2. Prerequisites
  3. Schema-First Discovery
  4. Getting Started for Agents
  5. Module Overview
  6. Common Workflows
  7. Input Options
  8. Output Formats
  9. Gotchas & Limitations
  10. Error Handling
Original SKILL.md headings · 285 lines, 1,651 words
SKILL.md preview
---
name: lightroom-cli
description: |
  Control Adobe Lightroom Classic via CLI. Use when the user wants to interact
  with Lightroom — adjust develop settings, manage catalog, navigate photos,
  apply presets, or automate photo workflows. Triggers: "Lightroomで",
  "現像設定を", "写真を編集", "カタログから", "lr コマンド", "プリセットを適用",
  "写真の露出", "ホワイトバランス", "プレビュー生成", "写真を検索".
  Do NOT use for general image editing unrelated to Lightroom Classic.
---

# Lightroom CLI Skills for Claude Code (v1.2.0+)

## Agent Quick Contract

1. **Always use `-o json`** (or pipe) for machine-readable output
2. **Always use `--fields`** to limit response size: `lr --fields id,filename catalog list`
3. **Check `lr schema CMD`** for parameter types and ranges before calling
4. **Use `--dry-run`** before mutating commands to preview changes
5. **Exit codes matter**: 0=ok, 2=validation, 3=connection, 4=timeout
6. **`requires_confirm` commands** need `--confirm` flag (see Destructive Commands below)

## Prerequisites

- lightroom-cli installed (`lr --version` to verify)
- Lightroom Classic running with plugin active
- Connection verified (`lr system check-connection`)

## Schema-First Discovery

Use `lr schema` to discover commands dynamically — don't memorize command lists.

```bash
lr schema                      # List all module groups
lr schema develop              # List commands in a group
lr schema develop.set          # Show command detail with parameters
lr develop range Exposure      # Get min/max for a develop parameter
```

**Example** (`lr -o json schema develop.set`):
```json
{"command": "develop.set", "mutating": true, "supports_dry_run": true, "requires_confirm": false, "risk_level": "write", "params": [{"name": "parameter", "type": "string", "required": true}, {"name": "value", "type": "float", "required": true}], "response_fields": ["parameter", "value", "previousValue"]}
```

## Getting Started for Agents

### Step 1: Verify connection

```bash
lr system check-connection
```

If unavailable, ensure Lightroom Classic is running with the plugin active.

### Step 2: Get photo IDs

```bash
# Get currently selected photos (most common)
lr -o json catalog get-selected
# Returns: {"photos": [{"id": "12345", "filename": "IMG_001.jpg", ...}], "count": 1}

# Or list all photos
lr -o json --fields id,filename catalog list --limit 10
```

The `id` field in each photo object is the PHOTO_ID used in subsequent commands.

### Step 3: Operate on photos

```bash
# Read settings
lr -o json develop get-settings

# Modify settings (values are ABSOLUTE, not relative — see Gotchas)
lr develop set Exposure 0.5 Contrast 25

# Set metadata
lr catalog set-rating 12345 5
```

### catalog vs selection

| | catalog | selection |
|---|---------|-----------|
| **Target** | Specific photo by ID | Currently selected photo(s) |
| **Use when** | You know the exact photo ID | Operating on what the user is viewing |
| **Agent preference** | Recommended (explicit, predictable) | Use for navigation workflows |

**Key:** `develop` commands implicitly target the currently selected photo(s). Use `catalog select PHOTO_ID` to set the target first, then `develop set ...`.

## Module Overview

Discover full command lists with `lr schema MODULE`. Below is what each module does.

- **system** — Connection management: ping, status, check-connection, reconnect
- **catalog** — Photo management: list, find, get-info, set-rating, add-keywords, set-flag, collections, collection-photos, folders, develop-presets, metadata operations. Use explicit PHOTO_ID for predictable results.
- **develop** — Image editing: get/set parameters, auto-tone, auto-wb, reset, apply JSON settings, presets, snapshots, tone curve, AI masks (subject/sky/background/etc with `--adjust`), graduated/radial/brush filters, local adjustments, crop/transform resets
- **selection** — Navigation & flagging: next/previous, flag/reject/unflag, set-rating, color-label, select-all/none/inverse
- **preview** — Preview generation: generate for current/batch, get preview info
- **plugin** — Plugin management: install, uninstall, status

## Common Workflows

### Relative value adjustment (values are absolute!)

```bash
lr -o json develop get Exposure        # 1. Read current value (e.g., 0.3)
# 2. Compute new value: 0.3 + 0.5 = 0.8
lr develop set Exposure 0.8            # 3. Set absolute value
```

### Batch find + mutate (agent pattern)

```bash
# 1. Find photos matching criteria
lr -o json --fields photos.id catalog find --rating 4 --rating-op ">="
# 2. Parse JSON → loop over photos[].id
lr catalog add-keywords PHOTO_ID1 portfolio
lr catalog add-keywords PHOTO_ID2 portfolio
```

> **Note:** There is no "find and mutate" single command. Parse JSON from `find`/`list` and call mutating commands per photo ID.

### catalog find — filter options

Basic: `--rating`, `--rating-op`, `--flag`, `--color-label`, `--camera`
Extended (v1.2.0): `--folder-path`, `--capture-date-from/to`, `--file-format`, `--keyword`, `--filename`

Full examples and notes → `references/catalog-find-filters.md`

### Safe editing with snapshots

```bash
lr develop snapshot "before-edit"           # 1. Checkpoint (no undo command exists!)
lr develop set Exposure 1.0 Contrast 25     # 2. Edit
lr develop reset                            # 3. Revert if unhappy
```

### AI mask with adjustments

```bash
lr develop ai sky --adjust '{"Exposure": -1.0, "Highlights": -30}'   # Darken sky
lr develop ai subject --adjust-preset brighten-subject               # Named preset
lr -o json develop ai presets                                        # List presets
```

### Apply consistent edits across photos

```bash
lr -o json develop get-settings                              # 1. Get reference
lr develop apply --settings '{"Exposure": 1.0, "Contrast": 25}'  # 2. Apply to others
```

## Input Options

### --dry-run

All mutating commands support `--dry-run` to preview what would be executed:

```bash
lr develop set Exposure 1.0 --dry-run
# Returns: {"dry_run": true, "command": "develop.setValue", "risk_level": "write", "params": {...}}
```

### --json Input

```bash
lr develop set --json '{"parameter": "Exposure", "value": 1.0}'
echo '{"parameter": "Contrast", "value": 25}' | lr develop set --json-stdin
```

> **Limitation:** `--json` cannot bypass required Click positional arguments. Use it primarily for commands where all parameters are options.

## Output Formats

The CLI auto-detects TTY vs pipe: text in TTY, JSON in pipe. Override with `-o json|text|table`.

Use `--fields` (global option, before subcommand) to select specific fields. Dot notation filters nested arrays:
```bash
lr --fields Exposure,Contrast -o json develop get-settings
lr --fields photos.id -o json catalog find --rating 5
# → {"photos": [{"id": "123"}, {"id": "456"}]}
```

### Recommended `--fields` patterns

| Use case | Recommended fields |
|----------|-------------------|
| Photo listing / search | `--fields id,filename,rating` |
| Photo detail | `--fields id,filename,rating,colorLabel,flag,keywords` |
| Develop settings overview | `--fields Exposure,Contrast,Highlights,Shadows,Whites,Blacks` |
| Color grading | `--fields Temperature,Tint,Vibrance,Saturation` |
| Tone curve | `--fields ToneCurve,ToneCurvePV2012` |
| Batch find (ID only) | `--fields photos.id` |

## Gotchas & Limitations

### Destructive commands (require `--confirm`)

| Command | Effect |
|---------|--------|
| `lr catalog remove-from-catalog PHOTO_ID --confirm` | Remove from catalog (not disk) |
| `lr develop ai reset --confirm` | Remove all masks from photo |

Omitting `--confirm` returns a structured error with the suggestion to add it.

### Values are absolute, not relative

`lr develop set Exposure 0.5` sets Exposure **to** 0.5, not +0.5 from current. To make relative changes: read current → compute → set. See "Relative value adjustment" workflow.

### No Undo/Redo

There is no undo command. **Always** run `lr develop snapshot "name"` before significant edits. To revert: `lr develop reset` and re-apply from the snapshot.

### Batch editing

For single-parameter batch edits across multiple photos, use `batch-set`:

```bash
lr develop batch-set --photo-ids 123,456,789 Exposure 0.5
```

For more complex batch edits (different parameters per photo), use the "Batch find + mutate" pattern: `find` → parse JSON → loop mutating commands per ID.

### Preset listing & search

```bash
lr -o json catalog develop-presets                    # List all presets (name + folder)
lr -o json catalog develop-presets --query "Portra"   # Search by preset name or folder name
```

Then apply: `lr develop preset "PRESET_NAME"`

### Collection photos

```bash
lr -o json catalog collections                           # List collections with IDs
lr -o json catalog collection-photos COLLECTION_ID       # Get photos from a collection
lr -o json catalog collection-photos 12345 --limit 100   # With pagination
```

### Other limitations

- **Preview = file path**: `lr preview generate` returns a file path on disk, not image data
- **Single connection**: Only one CLI session at a time
- **Out-of-range values**: Rejected with validation error. Use `lr develop range PARAM` to check

## Error Handling

Structured JSON errors with `code`, `message`, and `suggestions` fields:
```json
{"error": {"code": "VALIDATION_ERROR", "message": "...", "suggestions": ["..."]}}
```

### Exit code recovery playbook

| Exit Code | Meaning | Recovery |
|-----------|---------|----------|
| 0 | Success | — |
| 1 | General error | Read error message, adjust parameters |
| 2 | Validation error | Check `lr schema CMD` for valid params/types/ranges |
| 3 | Connection error | `lr system check-connection` → ensure Lightroom running → `lr system reconnect` |
| 4 | Timeout | Retry with `-t SECONDS` (default 30s; preview ops may need 120s+) |

## Environment Variables & MCP Server

Environment variables (`LR_PORT_FILE`, `LR_OUTPUT`, `LR_TIMEOUT`, etc.) and MCP Server setup → `references/environment-and-mcp.md`

## Troubleshooting

### Connection issues

| Symptom | Cause | Recovery |
|---------|-------|----------|
| Exit code 3 / `RESULT_UNKNOWN` | Connection dropped while a command was running; it may or may not have been applied, so it was not resent | Read the current state first (`lr develop get-settings`, `lr selection get-*`, ...) and re-run only if it did not apply |
| Exit code 3 / "Connection refused" | Lightroom not running or plugin disabled | 1. Verify Lightroom is running → 2. File > Plug-in Manager: check "Lightroom CLI Bridge" is enabled → 3. `lr system reconnect` |
| "Port file not found" | Port file not generated | 1. Restart Lightroom → 2. Confirm plugin shows "Start CLI Bridge" → 3. `ls /tmp/lightroom_ports.txt` to verify |
| "Connection timeout" after reconnect | Stale port info | 1. `rm /tmp/lightroom_ports.txt` → 2. In Lightroom: Stop plugin → Start plugin → 3. `lr system check-connection` |
| "Already connected" error | Another session is connected | 1. Check if `lr` is running in another terminal → 2. `lr system reconnect --force` |

### Plugin issues

| Symptom | Cause | Recovery |
|---------|-------|----------|
| Plugin not shown in Plug-in Manager | Wrong install path | 1. `lr plugin status` to check path → 2. `lr plugin install` to reinstall → 3. Restart Lightroom |
| "Plugin is disabled" | Lightroom disabled it | File > Plug-in Manager → click "Enable" → `lr system check-connection` |

### Command issues

| Symptom | Cause | Recovery |
|---------|-------|----------|
| Exit code 2 / "VALIDATION_ERROR" | Invalid parameters | Check `lr schema CMD` for correct types/ranges → `lr develop range PARAM` for value bounds |
| Exit code 4 / Timeout | Heavy operation | Add `-t 120` to extend timeout (preview ops need 120s+) |
| "No photo selected" | No target photo | `lr catalog select PHOTO_ID` first, then retry |
Files in this package (3)
  • SKILL.md 12 KB
  • references/catalog-find-filters.md 1 KB
  • references/environment-and-mcp.md 1 KB

Versions

The database has no other skills named lightroom-cli.

Database snapshot: 13.11.2026 · package version 9f1620772e60 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100lightroom-agent
    Cull and colour-grade photos in Adobe Lightroom Classic on this computer. Use when the user wants to pick the best shots from a shoot (sharpness, closed eyes, duplicates, expressions), rate/flag photos or build a picks collection, apply a consistent look or colour style (e.g.…
  • 100raw-photo-lightroom-preset
    Use for RAW photo culling, Lightroom Classic or Camera Raw editing, reference-style matching, closed-loop Lightroom MCP adjustments, lighting-cluster preset creation, XMP fallback generation, NEF/DNG/TIFF preview workflows, or Chinese requests about matching previous edits.…
  • 100adobe-upgrade-migration
    Migrate Adobe integrations away from Service Account JWT, Photoshop v1, retired Lightroom Firefly Services, or drifting SDK/API contracts with canaries and rollback. Use when the task requires adobe end-of-life and contract migration. Trigger with "upgrade Adobe integration",…
  • 85adobe-free-alternatives-cheatsheet
    Use when the user looks for free or open-source alternatives to Adobe software such as Photoshop, Illustrator, Premiere Pro, Lightroom, After Effects or Acrobat, with platform support and an install command for each alternative.
  • 100lightcraft-photos
    Organise photo libraries and develop raw/JPEG photos non-destructively in LightCraft (ArtCraft's Lightroom-class photo library and raw developer, via the `lightcraft` MCP server (mcp__lightcraft__*) or `lightcraft-cli`). Use whenever the user mentions LightCraft or the…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.