Skip to content

Server commands

Single sign-on for Frameleaf: connect Keycloak, Authentik or your own provider Watch on YouTube

The Frameleaf server image, ghcr.io/frameleaf/frameleaf-server, includes an administration tool called frameleaf-admin. It gets you out of a tight spot when the web app can’t: back in after losing the admin password, maintenance mode on or off, or a whole server recovered from backup.

From the folder with your docker-compose.yml:

Terminal window
docker exec frameleaf_server frameleaf-admin <command>

For commands that ask questions, add -it after exec. Or open a shell in the container and run commands from there:

Terminal window
docker exec -it frameleaf_server bash
frameleaf-admin <command>

Use the actual container name shown in your installation if it differs from frameleaf_server. On a Manager installation it does: the name is on Manager’s Containers page under Container name, or find it with:

Terminal window
docker ps --format '{{.Names}}' --filter label=com.docker.compose.service=frameleaf-server

In a manual installation you can also use the Compose service name, which never changes: docker compose exec frameleaf-server frameleaf-admin <command>.

Command What it does
help Show help
reset-admin-password Reset the administrator’s password
disable-password-login Turn off password sign-in
enable-password-login Turn on password sign-in
disable-oauth-login Turn off sign-in with your own provider (OAuth)
enable-oauth-login Turn on sign-in with your own provider (OAuth)
reset-sign-in-policy Put Require a passkey or two-step back to Administrators away from home
enable-maintenance-mode Turn on maintenance mode, or get a new sign-in address for it
disable-maintenance-mode Turn off maintenance mode
list-users List the accounts on the server
grant-admin Make an account an administrator, by email
revoke-admin Remove administrator rights from an account, by email
version Print the Frameleaf version
change-media-location Rewrite file paths in the database after the media folder moves
schema-check Check database migrations and look for schema drift
cloud-backup restore Restore from a backup bucket or independent local export, without the web app
cloud-backup prepare-client-key Write a new recovery key file from an existing backup key file. Only the local file is changed; nothing is sent anywhere
import-immich The one-time import of an Immich library. Manager runs it for you; see Switch from Immich

The tool has a few more commands that Manager uses while it imports or restores a library, such as import-library, restore-state and validate-restore. They aren’t meant to be run by hand.

$ frameleaf-admin reset-admin-password
Found Admin:
- ID=e65e6f88-2a30-4dbe-8dd9-1885f4889b53
- OAuth ID=
- Name=Frameleaf Admin
? Please choose a new password (optional) frameleaf-is-cool
? Invalidate existing sessions? Yes
The admin password has been updated.

Leave the password blank and the command makes up a random one and prints it. Answer Yes to sign the administrator out everywhere, which is the safe choice if someone else may know the old password.

$ frameleaf-admin disable-password-login
Password login has been disabled.
$ frameleaf-admin enable-password-login
Password login has been enabled.
$ frameleaf-admin enable-oauth-login
OAuth login has been enabled.
$ frameleaf-admin disable-oauth-login
OAuth login has been disabled.
$ frameleaf-admin reset-sign-in-policy
"Require a passkey or two-step" is back to administrators away from home.

If a sign-in provider change locks everyone out, turn password sign-in back on with enable-password-login. If Require a passkey or two-step keeps you out, reset-sign-in-policy puts it back to the default.

$ frameleaf-admin enable-maintenance-mode
Maintenance mode has been enabled.
Log in using the following URL:
https://photos.example.com/maintenance?token=<token>
$ frameleaf-admin disable-maintenance-mode
Maintenance mode has been disabled.

The sign-in address works for 4 hours. Run enable-maintenance-mode again for a new one; it then says the server is already in maintenance mode and prints a fresh address.

$ frameleaf-admin list-users
[
{
id: 'e65e6f88-2a30-4dbe-8dd9-1885f4889b53',
name: 'Frameleaf Admin',
storageLabel: 'admin',
isAdmin: true,
...
}
]
$ frameleaf-admin grant-admin
? Please enter the user email: [email protected]
Admin access has been granted to [email protected]
$ frameleaf-admin revoke-admin
? Please enter the user email: [email protected]
Admin access has been revoked from [email protected]

If the media folder is mounted at a different path inside the container than before, for example after moving to new hardware, the database still points at the old paths. Back up the database first, then:

$ frameleaf-admin change-media-location
? Enter the previous value of FRAMELEAF_MEDIA_LOCATION: /data
? Enter the new value of FRAMELEAF_MEDIA_LOCATION: /my-data
...
Previous value: /data
Current value: /my-data
Changing database paths from "/data/*" to "/my-data/*"
? Do you want to proceed? [Y/n] y
Database file paths updated successfully!

Then set FRAMELEAF_MEDIA_LOCATION to the new value and restart.

$ frameleaf-admin schema-check
Migrations are up to date
No schema drift detected
$ frameleaf-admin version
v<major>.<minor>.<patch>

If the server is lost, cloud-backup restore brings back its files and database from its Cloud backup bucket onto a fresh installation, straight from the command line. Secrets come from environment variables, never the command line, so they stay out of your shell history.

Terminal window
read -rs FRAMELEAF_BACKUP_SECRET_ACCESS_KEY && export FRAMELEAF_BACKUP_SECRET_ACCESS_KEY
frameleaf-admin cloud-backup restore \
--bucket <bucket> \
--endpoint https://storage.example \
--access-key-id <access key ID> \
--key-file /path/to/backup-key-file
Option What it’s for
--bucket <name> The backup bucket. Required
--endpoint <url> The storage address. Required
--access-key-id <id> The access key ID. Required. Its secret is read from FRAMELEAF_BACKUP_SECRET_ACCESS_KEY
--region <region> The region. Read from the storage address if you leave it out
--key-file <path> The backup key file, or a file holding the recovery code
--escrow-file <path> Instead of --key-file: a key copy from your Frameleaf account. Its passphrase is read from FRAMELEAF_BACKUP_ESCROW_PASSPHRASE
--manifest <key> Select an exact historical backup. Required when exporting from your own storage bucket; client-encrypted recovery uses trusted local snapshot history when omitted
--scope <scope> library (default): files in place and the database dump. files: files into a restore folder. database: the dump only
--restore-database Also restore the database from the dump, replacing the current one
--export-directory <path> Export the backup to a new local folder instead of restoring it. See Export and recover without Cloud access
--managed With --export-directory, on the linked server: export its Frameleaf-managed backup without storage credentials. See Export a managed backup
--offline-directory <path> Restore from a complete local export, with no storage credentials or Cloud account
--history-file <path> The trusted snapshot history saved from the original server, when your key file doesn’t include it

Give the key with either --key-file or --escrow-file, not both. Without --restore-database, the database dump is left in the backups folder for you to restore from Settings, then Maintenance (see Backup and restore). After a database restore, start the server and set up cloud backup again.

cloud-backup prepare-client-key writes a new recovery key file from an existing one, so the file can unlock client-encrypted backups. It never overwrites a file and contacts nothing:

Terminal window
frameleaf-admin cloud-backup prepare-client-key \
--key-file /private/backup-key.json \
--output-file /private/backup-key-new.json

Add --rotate to a key file that’s already prepared to keep its earlier keys, for older snapshots, and add a new one for future backups. Keep a copy of the new file away from the server before you use it.

An independent export is a complete, self-contained copy of your backup that you can recover anywhere, with no storage credentials and no Cloud account. You need storage access only while you create it. Use the recovery tools from your server’s release, and check that your managed storage offers the recovery access this needs.

Keep the complete recovery key file on another device. For client-encrypted backups it contains every root-key version used by retained backups and trusted snapshot history. Frameleaf-managed backups are client-encrypted. Backups in your own storage bucket use provider-key encryption.

The server linked to a Frameleaf-managed backup can export it without any storage credentials. It gets read-only access to its own backup and renews it while the export runs, so a long export doesn’t lose access part-way. Run it on that server while it’s still linked:

Terminal window
frameleaf-admin cloud-backup restore --managed \
--key-file /private/current-recovery-key.json \
--export-directory /private/frameleaf-export

Use the complete, current recovery key file you saved at setup or after your last key change. The command checks that it belongs to this server’s backup before it asks for access. It exports the newest trusted snapshot; add --manifest <key> to choose an older one. --managed only exports, so it can’t be combined with --bucket, --endpoint, --access-key-id, --region, --offline-directory or --restore-database. To recover, use --offline-directory on the replacement server, as shown below.

To export a restore point from your own bucket, give the storage address, region and exact manifest for your backup, with the secret in the environment:

Terminal window
read -rs FRAMELEAF_BACKUP_SECRET_ACCESS_KEY && export FRAMELEAF_BACKUP_SECRET_ACCESS_KEY
frameleaf-admin cloud-backup restore \
--bucket family-backup \
--endpoint https://storage.example \
--region us-east-1 \
--access-key-id SYNTHETIC_ACCESS_KEY \
--key-file /private/backup-key.json \
--manifest m/2026-10-10T02:00:00.000Z.json.gz \
--export-directory /private/frameleaf-export

Export into a new, empty folder and keep everything in it together: key-file.json holds the keys to recover it, and objects holds the files for the selected snapshot, including its database dump. Exports from your own bucket contain plaintext file contents, because provider encryption is removed during export; client-format objects stay encrypted. Either way, store the export privately. It’s complete once its checks for missing or corrupt references pass.

For client-encrypted recovery, the trusted history in the complete key file picks the right snapshot for you. If your key file doesn’t include it, add --history-file /private/cloud-backup-history.json with the trusted copy saved from the original server; a history taken only from the bucket listing isn’t trusted for this. Use --manifest to choose a specific historical snapshot, and refresh your recovery files after each key rotation.

Copy the complete export to a replacement server and configure its media and backup paths. Then:

Terminal window
frameleaf-admin cloud-backup restore \
--offline-directory /private/frameleaf-export \
--key-file /private/frameleaf-export/key-file.json \
--scope library

library restores files to their configured paths and leaves the database dump in the backup folder. Any different file already in the way is moved aside, not overwritten. Use --scope files for a separate restore folder, or --scope database for the dump alone. The export itself is only read, and recovery stops if any data is missing or corrupt.

When you’re ready to apply the database, check the dump, configuration and destination, then add --restore-database, which replaces the current database. Stop the replacement server’s API and job containers first, and use a Frameleaf release that matches the backup’s server and database version. Follow Backup and restore, then open the running library and check your photos to confirm the recovery.