The photoprism cluster commands manage a PhotoPrism® Portal cluster from a terminal. Some commands run on an instance (to join a cluster and pull its theme), while the cluster-management commands run on the Portal, where they operate directly on the cluster registry.
Run these commands in a terminal, for example docker compose exec photoprism photoprism cluster summary. Users of Red Hat Enterprise Linux® and compatible distributions can substitute docker and docker compose with podman and podman-compose.
Commands on a Node
These commands are available on every instance and are used to join a cluster and keep its theme up to date.
Registering a Node
photoprism cluster register registers the current node with the Portal, or updates its credentials. It is normally run automatically on startup (see Adding Instances), but you can run it manually to preview the request or to persist the returned credentials:
photoprism cluster register --name acme --role instance --write-config
| Command Flag | Description |
|---|---|
--name NAME | node name (lowercase letters, digits, hyphens) |
--role ROLE | node role, instance (default) or service |
--portal-url URL | Portal base URL (defaults to the configured value) |
--join-token TOKEN | Portal join token (defaults to the configured value) |
--advertise-url URL | internal URL the Portal uses to reach this node |
--site-url URL | public site URL (https://...) |
--label k=v | attach a label; repeat to add more |
--rotate | rotate the node’s database password |
--rotate-secret | rotate the node’s client secret |
--write-config | persist returned secrets and database settings to the local config |
--force, -f | confirm actions that may overwrite local data (e.g. with --write-config) |
--dry-run, --dry | print the derived values and request payload without contacting the Portal |
Secrets are printed only once, when they are first issued or rotated, and are written to disk only with --write-config (with strict 0600 permissions). They are never written to log files.
Generating a Join Token
photoprism cluster join-token generates a Portal join token that instances use to register. Use --save to write it to the Portal’s secrets directory:
photoprism cluster join-token --save
Pulling the Theme
photoprism cluster theme pull downloads the branding theme from the Portal and installs it locally. If only a join token is available, the command registers the node first to obtain credentials, then downloads the theme:
photoprism cluster theme pull
| Command Flag | Description |
|---|---|
--dest PATH | extract to a different directory (defaults to the configured theme path) |
--force, -f | replace existing files at the destination |
--portal-url URL | Portal base URL (defaults to the configured value) |
--join-token TOKEN | Portal join token (defaults to the configured value) |
--client-id ID | node client ID (defaults to the configured value) |
--client-secret SECRET | node client secret (defaults to the configured value) |
Commands on the Portal
These commands run on the Portal and operate on the cluster registry. They accept a target node by its UUID (preferred), its client ID, or its name.
Cluster Status
photoprism cluster summary # cluster UUID, network, node count, database, and theme version
photoprism cluster health # current cluster health status
Managing Nodes
photoprism cluster nodes ls # list registered nodes
photoprism cluster nodes show acme # show details for one node
photoprism cluster nodes mod acme --role service --advertise-url http://acme:2342
photoprism cluster nodes rotate acme --db # rotate the database password (use --secret for the client secret)
photoprism cluster nodes rm acme # remove a node (add --drop-db to also drop its database)
| Command | Description |
|---|---|
nodes ls | list registered nodes (--count, --offset for paging) |
nodes show | show a node’s details, including its database driver |
nodes mod | change a node’s role, display name, advertise URL, or labels |
nodes rotate | rotate a node’s database password (--db) and/or client secret (--secret) |
nodes rm | remove a node from the registry; --drop-db also drops its provisioned database |
Destructive commands (nodes mod, nodes rm, nodes rotate) prompt for confirmation. Pass --yes (-y) to run them non-interactively, or --dry-run to preview the effect without making changes.
Granting User Access
The cluster users access commands manage which users can open which instances (see Cluster Authentication & Access Control):
photoprism cluster users access ls --user [user-uid]
photoprism cluster users access grant --user [user-uid] --node [node-uuid] --role viewer
photoprism cluster users access revoke --user [user-uid] --node [node-uuid]
To admit a whole security group to an instance, use cluster nodes allow-group:
photoprism cluster nodes allow-group [node-uuid] [group-id] --role user
Output Formats
Most cluster commands support machine-readable output for scripting and automation:
| Command Flag | Description |
|---|---|
--json, -j | print a single JSON document |
--md, -m | format as Markdown |
--csv, -c | export as semicolon separated values |
--tsv, -t | export as tab separated values |
When --json is set, the command prints only the JSON result and suppresses interactive messages, so it can be piped into tools such as jq.
Exit Codes
The cluster commands return predictable exit codes for use in scripts:
| Code | Meaning |
|---|---|
0 | success |
1 | unexpected or internal error |
2 | usage or validation error (e.g. invalid flag or name) |
3 | not found (e.g. unknown node ID or name) |
4 | unauthorized (missing or invalid token, insufficient privileges) |
5 | conflict (e.g. name already in use, rotation rejected) |
6 | rate-limited (the Portal returned too many requests) |
PhotoPrism® Documentation
For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:
