---
name: pp-immich
description: "Agent-native control and careful personal-library rituals for a self-hosted Immich instance. Trigger phrases: `make a shared album from our beach weekend`, `find duplicate screenshots`, `show photos of me and Dad from past Julys`, `show my Immich memories`, `check my Immich server health`, `use Immich`."
author: "avanderheyde"
license: "Apache-2.0"
argument-hint: "<command> [args] | install cli|mcp"
allowed-tools: "Read Bash"
metadata:
  openclaw:
    requires:
      bins:
        - immich-pp-cli
    install:
      - kind: go
        bins: [immich-pp-cli]
        module: github.com/mvanhorn/printing-press-library/library/media-and-entertainment/immich/cmd/immich-pp-cli
---
<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/media-and-entertainment/immich/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Immich — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `immich-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install immich --cli-only
   ```
2. Verify: `immich-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.5 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead:

```bash
go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/immich/cmd/immich-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

Covers Immich's official v3 API, the upload/import strengths of immich-go, and the broad raw operations of ImmichMCP, then adds safe personal workflows for events, duplicate cleanup, family time queries, memories, stacks, partners, and jobs.

## When to Use This CLI

Use this CLI for your own or a delegated self-hosted Immich library: finding and sharing event photos, safely dealing with duplicates, browsing people/time memories, and checking the health of the host.

## Anti-triggers

Do not use this CLI for:
- Do not use it against an Immich instance you are not authorized to access.
- Do not run duplicate resolution or asset deletion without reviewing the preview output.
- Do not expect it to replace a local backup of your original photos.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Shared events
- **`album event`** — Create or update a reviewable shared event album from explicit Immich search filters.

  _Use it when an agent needs to make a shareable event collection without manually copying asset IDs._

  ```bash
  immich-pp-cli album event beach-weekend --from 2025-07-01 --to 2025-07-07 --dry-run --agent
  ```

### Safe cleanup
- **`duplicates plan`** — Preview native duplicate groups and a deterministic keeper proposal without changing assets.

  _Use it before any destructive duplicate cleanup._

  ```bash
  immich-pp-cli duplicates plan --limit 20 --agent
  ```
- **`duplicates apply`** — Resolve selected native duplicate groups only after an explicit apply confirmation.

  _Use it only after reviewing a duplicate plan. Include that plan's exact `evidence` array for every selected group; when the server has no keeper recommendation, also include an explicit keeper. Apply rejects missing or changed evidence before choosing assets to trash._

  ```bash
  immich-pp-cli duplicates apply --groups '[{"group_id":"group-id","keeper":"asset-to-keep","evidence":["asset-to-keep","asset-to-trash"]}]' --apply --agent
  ```

### Family archive
- **`people july`** — Find one or two people across past Julys using real people and metadata search endpoints.

  _Use it for questions such as photos of me and Dad from past Julys._

  ```bash
  immich-pp-cli people july --person me --person dad --years 5 --agent
  ```
- **`memories review`** — List recent native memories with their dates and asset counts for an intentional review.

  _Use it to revisit what Immich surfaced without paging through the web UI._

  ```bash
  immich-pp-cli memories review --limit 12 --agent
  ```

### Library curation
- **`library review`** — Review bounded favorite and archived asset search results without mutating the library.

  _Use it to curate favorites and archived material deliberately._

  ```bash
  immich-pp-cli library review --mode favorites --limit 25 --agent
  ```
- **`stacks review`** — Inspect native stacks for empty, singleton, and unusually large groups without changing them.

  _Use it to understand burst and RAW/JPEG grouping before editing a stack._

  ```bash
  immich-pp-cli stacks review --limit 50 --agent
  ```

### Self-hosted maintenance
- **`library health`** — Report partner-sharing and worker-queue facts from the configured Immich server.

  _Use it when a self-hosted photo library feels stale or a shared library is not behaving as expected._

  ```bash
  immich-pp-cli library health --agent
  ```

## Command Reference

**activities** — An activity is a like or a comment made by a user on an asset or album.

- `immich-pp-cli activities create-activity` — Create a like or a comment for an album, or an asset in an album.
- `immich-pp-cli activities delete-activity` — Removes a like or comment from a given album or asset in an album.
- `immich-pp-cli activities get` — Returns a list of activities for the selected asset or album.
- `immich-pp-cli activities get-activity-statistics` — Returns the number of likes and comments for a given album or asset in an album.

**admin** — Manage admin

- `immich-pp-cli admin create-notification` — Create a new notification for a specific user.
- `immich-pp-cli admin create-user` — Create a new user.
- `immich-pp-cli admin delete-database-backup` — Delete a backup by its filename
- `immich-pp-cli admin delete-integrity-report` — Delete a given report item and perform corresponding deletion (e.g. trash asset, delete file)
- `immich-pp-cli admin delete-user` — Delete a user.
- `immich-pp-cli admin detect-prior-install` — Collect integrity checks and other heuristics about local data.
- `immich-pp-cli admin download-database-backup` — Downloads the database backup file
- `immich-pp-cli admin get-integrity-report` — Get all flagged items by integrity report type
- `immich-pp-cli admin get-integrity-report-csv` — Get all integrity report entries for a given type as a CSV
- `immich-pp-cli admin get-integrity-report-file` — Download the untracked/broken file if one exists
- `immich-pp-cli admin get-integrity-report-summary` — Get a count of the items flagged in each integrity report
- `immich-pp-cli admin get-maintenance-status` — Fetch information about the currently running maintenance action.
- `immich-pp-cli admin get-notification-template` — Retrieve a preview of the provided email template.
- `immich-pp-cli admin get-user` — Retrieve a specific user by their ID.
- `immich-pp-cli admin get-user-calendar-heatmap` — Retrieve activity counts for a specified period, in a calendar heatmap format.
- `immich-pp-cli admin get-user-preferences` — Retrieve the preferences of a specific user.
- `immich-pp-cli admin get-user-sessions` — Retrieve all sessions for a specific user.
- `immich-pp-cli admin get-user-statistics` — Retrieve asset statistics for a specific user.
- `immich-pp-cli admin list-database-backups` — Get the list of the successful and failed backups
- `immich-pp-cli admin maintenance-login` — Login with maintenance token or cookie to receive current information and perform further actions.
- `immich-pp-cli admin restore-user` — Restore a previously deleted user.
- `immich-pp-cli admin search-users` — Search for users.
- `immich-pp-cli admin send-test-email` — Send a test email using the provided SMTP configuration.
- `immich-pp-cli admin set-maintenance-mode` — Put Immich into or take it out of maintenance mode
- `immich-pp-cli admin start-database-restore-flow` — Put Immich into maintenance mode to restore a backup (Immich must not be configured)
- `immich-pp-cli admin unlink-all-oauth-accounts` — Unlinks all OAuth accounts associated with user accounts in the system.
- `immich-pp-cli admin update-user` — Update an existing user.
- `immich-pp-cli admin update-user-preferences` — Update the preferences of a specific user.
- `immich-pp-cli admin upload-database-backup` — Uploads .sql/.sql.gz file to restore backup from

**albums** — An album is a collection of assets that can be shared with other users or via shared links.

- `immich-pp-cli albums add-assets-to` — Send a list of asset IDs and album IDs to add each asset to each album.
- `immich-pp-cli albums create` — Create a new album. The album can also be created with initial users and assets.
- `immich-pp-cli albums delete` — Delete a specific album by its ID.
- `immich-pp-cli albums get-all` — Retrieve a list of albums available to the authenticated user.
- `immich-pp-cli albums get-info` — Retrieve information about a specific album by its ID.
- `immich-pp-cli albums get-statistics` — Returns statistics about the albums available to the authenticated user.
- `immich-pp-cli albums update-info` — Update the information of a specific album by its ID.

**api-keys** — An api key can be used to programmatically access the Immich API.

- `immich-pp-cli api-keys create` — Creates a new API key. It will be limited to the permissions specified.
- `immich-pp-cli api-keys delete` — Deletes an API key identified by its ID. The current user must own this API key.
- `immich-pp-cli api-keys get` — Retrieve all API keys of the current user.
- `immich-pp-cli api-keys get-apikeys` — Retrieve an API key by its ID. The current user must own this API key.
- `immich-pp-cli api-keys get-my` — Retrieve the API key that is used to access this endpoint.
- `immich-pp-cli api-keys update` — Updates the name and permissions of an API key by its ID. The current user must own this API key.

**assets** — An asset is an image or video that has been uploaded to Immich.

- `immich-pp-cli assets check-bulk-upload` — Determine which assets have already been uploaded to the server based on their SHA1 checksums.
- `immich-pp-cli assets copy` — Copy asset information like albums, tags, etc. from one asset to another.
- `immich-pp-cli assets delete` — Deletes multiple assets at the same time.
- `immich-pp-cli assets delete-bulk-metadata` — Delete metadata key-value pairs for multiple assets.
- `immich-pp-cli assets get-info` — Retrieve detailed information about a specific asset.
- `immich-pp-cli assets get-statistics` — Retrieve various statistics about the assets owned by the authenticated user.
- `immich-pp-cli assets run-jobs` — Run a specific job on a set of assets.
- `immich-pp-cli assets update` — Updates multiple assets at the same time.
- `immich-pp-cli assets update-bulk-metadata` — Upsert metadata key-value pairs for multiple assets.
- `immich-pp-cli assets update-id` — Update information of a specific asset.
- `immich-pp-cli assets upload` — Uploads a new asset to the server.

**download** — Endpoints for downloading assets or collections of assets.

- `immich-pp-cli download archive` — Download a ZIP archive containing the specified assets.
- `immich-pp-cli download get-info` — Retrieve information about how to request a download for the specified assets or album.

**duplicates** — Endpoints for managing and identifying duplicate assets.

- `immich-pp-cli duplicates delete` — Delete multiple duplicate assets specified by their IDs.
- `immich-pp-cli duplicates delete-id` — Dismiss a duplicate group by its ID, unlinking all assets in the group without deleting them.
- `immich-pp-cli duplicates get-asset` — Retrieve a list of duplicate assets available to the authenticated user.
- `immich-pp-cli duplicates resolve` — Resolve duplicate groups by synchronizing metadata across assets and deleting/trashing duplicates.

**faces** — A face is a detected human face within an asset, which can be associated with a person. Faces are normally detected via machine learning, but can also be created manually.

- `immich-pp-cli faces create` — Create a new face that has not been discovered by facial recognition.
- `immich-pp-cli faces delete` — Delete a face identified by the id. Optionally can be force deleted.
- `immich-pp-cli faces get` — Retrieve all faces belonging to an asset.
- `immich-pp-cli faces reassign-by-id` — Re-assign the face provided in the body to the person identified by the id in the path parameter.

**immich-auth** — Manage immich auth

- `immich-pp-cli immich-auth change-password` — Change the password of the current user.
- `immich-pp-cli immich-auth change-pin-code` — Change the pin code for the current user.
- `immich-pp-cli immich-auth get-status` — Get information about the current session, including whether the user has a password
- `immich-pp-cli immich-auth lock-session` — Remove elevated access to locked assets from the current session.
- `immich-pp-cli immich-auth login` — Login with username and password and receive a session token.
- `immich-pp-cli immich-auth logout` — Logout the current user and invalidate the session token.
- `immich-pp-cli immich-auth reset-pin-code` — Reset the pin code for the current user by providing the account password
- `immich-pp-cli immich-auth setup-pin-code` — Setup a new pin code for the current user.
- `immich-pp-cli immich-auth sign-up-admin` — Create the first admin user in the system.
- `immich-pp-cli immich-auth unlock-session` — Temporarily grant the session elevated access to locked assets by providing the correct PIN code.
- `immich-pp-cli immich-auth validate-access-token` — Validate the current authorization method is still valid.

**immich-jobs** — Manage immich jobs

- `immich-pp-cli immich-jobs create` — Run a specific job.
- `immich-pp-cli immich-jobs get-queues-legacy` — Retrieve the counts of the current queue, as well as the current status.
- `immich-pp-cli immich-jobs run-queue-command-legacy` — Queue all assets for a specific job type.

**immich-search** — Manage immich search

- `immich-pp-cli immich-search asset-statistics` — Retrieve statistical data about assets based on search criteria, such as the total matching count.
- `immich-pp-cli immich-search assets` — Search for assets based on various metadata criteria.
- `immich-pp-cli immich-search get-assets-by-city` — Retrieve a list of assets with each asset belonging to a different city.
- `immich-pp-cli immich-search get-explore-data` — Retrieve data for the explore section, such as popular people and places.
- `immich-pp-cli immich-search get-suggestions` — Retrieve search suggestions based on partial input. This endpoint is used for typeahead search features.
- `immich-pp-cli immich-search large-assets` — Search for assets that are considered large based on specified criteria.
- `immich-pp-cli immich-search person` — Search for people by name.
- `immich-pp-cli immich-search places` — Search for places by name.
- `immich-pp-cli immich-search random` — Retrieve a random selection of assets based on the provided criteria.
- `immich-pp-cli immich-search smart` — Perform a smart search for assets by using machine learning vectors to determine relevance.

**immich-sync** — Manage immich sync

- `immich-pp-cli immich-sync delete-ack` — Delete specific synchronization acknowledgments.
- `immich-pp-cli immich-sync get-ack` — Retrieve the synchronization acknowledgments for the current session.
- `immich-pp-cli immich-sync get-stream` — Retrieve a JSON lines streamed response of changes for synchronization.
- `immich-pp-cli immich-sync send-ack` — Send a list of synchronization acknowledgements to confirm that the latest changes have been received.

**libraries** — An external library is made up of input file paths or expressions that are scanned for asset files. Discovered files are automatically imported. Assets much be unique within a library, but can be duplicated across libraries. Each user has a default upload library, and can have one or more external libraries.

- `immich-pp-cli libraries create-library` — Create a new external library.
- `immich-pp-cli libraries delete-library` — Delete an external library by its ID.
- `immich-pp-cli libraries get-all` — Retrieve a list of external libraries.
- `immich-pp-cli libraries get-library` — Retrieve an external library by its ID.
- `immich-pp-cli libraries update-library` — Update an existing external library.

**map** — Map endpoints include supplemental functionality related to geolocation, such as reverse geocoding and retrieving map markers for assets with geolocation data.

- `immich-pp-cli map get-markers` — Retrieve a list of latitude and longitude coordinates for every asset with location data.
- `immich-pp-cli map reverse-geocode` — Retrieve location information (e.g., city, country) for given latitude and longitude coordinates.

**memories** — A memory is a specialized collection of assets with dedicated viewing implementations in the web and mobile clients. A memory includes fields related to visibility and are automatically generated per user via a background job.

- `immich-pp-cli memories create-memory` — Create a new memory by providing a name, description, and a list of asset IDs to include in the memory.
- `immich-pp-cli memories delete-memory` — Delete a specific memory by its ID.
- `immich-pp-cli memories get-memory` — Retrieve a specific memory by its ID.
- `immich-pp-cli memories search` — Retrieve a list of memories.
- `immich-pp-cli memories statistics` — Retrieve statistics about memories, such as total count and other relevant metrics.
- `immich-pp-cli memories update-memory` — Update an existing memory by its ID.

**notifications** — A notification is a specialized message sent to users to inform them of important events. Currently, these notifications are only shown in the Immich web application.

- `immich-pp-cli notifications delete` — Delete a list of notifications at once.
- `immich-pp-cli notifications delete-id` — Delete a specific notification.
- `immich-pp-cli notifications get` — Retrieve a list of notifications.
- `immich-pp-cli notifications get-id` — Retrieve a specific notification identified by id.
- `immich-pp-cli notifications update` — Update a list of notifications. Allows to bulk-set the read status of notifications.
- `immich-pp-cli notifications update-id` — Update a specific notification to set its read status.

**oauth** — Manage oauth

- `immich-pp-cli oauth finish` — Complete the OAuth authorization process by exchanging the authorization code for a session token.
- `immich-pp-cli oauth link-account` — Link an OAuth account to the authenticated user.
- `immich-pp-cli oauth logout` — Logout the OAuth account and invalidate the session specified by the sid claim or all sessions if the sid claim is not
- `immich-pp-cli oauth redirect-to-mobile` — Requests to this URL are automatically forwarded to the mobile app, and is used in some cases for OAuth redirecting.
- `immich-pp-cli oauth start` — Initiate the OAuth authorization process.
- `immich-pp-cli oauth unlink-account` — Unlink the OAuth account from the authenticated user.

**partners** — A partner is a link with another user that allows sharing of assets between two users.

- `immich-pp-cli partners create` — Create a new partn