# Server commands

Source: https://frameleaf.app/docs/admin/server-commands/

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

From the folder with your `docker-compose.yml`:

```bash
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:

```bash
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](https://frameleaf.app/docs/admin/manager/#how-manager-runs-it) page under **Container name**, or find it with:

```bash
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>`.

## 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](https://frameleaf.app/docs/admin/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](https://frameleaf.app/docs/migrate/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

### Reset the admin password

```text
$ frameleaf-admin reset-admin-password
Found Admin:
- ID=e65e6f88-2a30-4dbe-8dd9-1885f4889b53
- OAuth ID=
- Email=admin@example.com
- 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.

### Sign-in options

```text
$ 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](https://frameleaf.app/docs/admin/sign-in-and-oauth/#require-a-passkey-or-two-step) keeps you out, `reset-sign-in-policy` puts it back to the default.

### Maintenance mode

```text
$ 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.

### Accounts and administrators

```text
$ frameleaf-admin list-users
[
  {
    id: 'e65e6f88-2a30-4dbe-8dd9-1885f4889b53',
    email: 'admin@example.com',
    name: 'Frameleaf Admin',
    storageLabel: 'admin',
    isAdmin: true,
    ...
  }
]

$ frameleaf-admin grant-admin
? Please enter the user email:  user@example.com
Admin access has been granted to user@example.com

$ frameleaf-admin revoke-admin
? Please enter the user email:  user@example.com
Admin access has been revoked from user@example.com
```

### 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:

```text
$ 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

```text
$ frameleaf-admin schema-check
Migrations are up to date

No schema drift detected
```

### Print the version

```text
$ frameleaf-admin version
v<major>.<minor>.<patch>
```

### Restore from a cloud backup bucket

If the server is lost, `cloud-backup restore` brings back its files and database from its [Cloud backup](https://frameleaf.app/docs/cloud/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.

```bash
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](#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](#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](https://frameleaf.app/docs/admin/backup-and-restore/#restore-a-database-backup)). After a database restore, start the server and set up cloud backup again.

### 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:

```bash
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.

### 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

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:

```bash
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.

#### 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:

```bash
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:

```bash
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](https://frameleaf.app/docs/admin/backup-and-restore/), then open the running library and check your photos to confirm the recovery.
