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.
How to run a command
Section titled “How to run a command”From the folder with your docker-compose.yml:
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:
docker exec -it frameleaf_server bashframeleaf-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:
docker ps --format '{{.Names}}' --filter label=com.docker.compose.service=frameleaf-serverIn a manual installation you can also use the Compose service name, which never changes: docker compose exec frameleaf-server frameleaf-admin <command>.
Commands
Section titled “Commands”| 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.
Examples
Section titled “Examples”Reset the admin password
Section titled “Reset the admin password”$ frameleaf-admin reset-admin-passwordFound Admin:- ID=e65e6f88-2a30-4dbe-8dd9-1885f4889b53- OAuth ID=- Name=Frameleaf Admin? Please choose a new password (optional) frameleaf-is-cool? Invalidate existing sessions? YesThe 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.
Sign-in options
Section titled “Sign-in options”$ frameleaf-admin disable-password-loginPassword login has been disabled.
$ frameleaf-admin enable-password-loginPassword login has been enabled.
$ frameleaf-admin enable-oauth-loginOAuth login has been enabled.
$ frameleaf-admin disable-oauth-loginOAuth 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.
Maintenance mode
Section titled “Maintenance mode”$ frameleaf-admin enable-maintenance-modeMaintenance mode has been enabled.
Log in using the following URL:https://photos.example.com/maintenance?token=<token>
$ frameleaf-admin disable-maintenance-modeMaintenance 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.
Accounts and administrators
Section titled “Accounts and administrators”$ frameleaf-admin list-users[ { id: 'e65e6f88-2a30-4dbe-8dd9-1885f4889b53', email: '[email protected]', 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]Change the media location
Section titled “Change the media location”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.
Check the database schema
Section titled “Check the database schema”$ frameleaf-admin schema-checkMigrations are up to date
No schema drift detectedPrint the version
Section titled “Print the version”$ frameleaf-admin versionv<major>.<minor>.<patch>Restore from a cloud backup bucket
Section titled “Restore from a cloud backup bucket”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.
read -rs FRAMELEAF_BACKUP_SECRET_ACCESS_KEY && export FRAMELEAF_BACKUP_SECRET_ACCESS_KEYframeleaf-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.
Prepare or rotate a recovery key file
Section titled “Prepare or rotate a recovery key file”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:
frameleaf-admin cloud-backup prepare-client-key \ --key-file /private/backup-key.json \ --output-file /private/backup-key-new.jsonAdd --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.
Export and recover without Cloud access
Section titled “Export and recover without Cloud access”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.
Export a managed backup
Section titled “Export a managed backup”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:
frameleaf-admin cloud-backup restore --managed \ --key-file /private/current-recovery-key.json \ --export-directory /private/frameleaf-exportUse 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.
Export from your own storage bucket
Section titled “Export from your own storage bucket”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:
read -rs FRAMELEAF_BACKUP_SECRET_ACCESS_KEY && export FRAMELEAF_BACKUP_SECRET_ACCESS_KEYframeleaf-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-exportExport 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:
frameleaf-admin cloud-backup restore \ --offline-directory /private/frameleaf-export \ --key-file /private/frameleaf-export/key-file.json \ --scope librarylibrary 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.
© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.
