Skip to content

API and command-line uploads

Upload whole folders with the Frameleaf CLI: API keys, dry run and albums Watch on YouTube

The Frameleaf CLI uploads whole folders from your computer in one command, turns folders into albums, skips duplicates and can keep watching for new files. It also moves a library between two Frameleaf servers. For your own integrations, use the Server API; its endpoint reference lists parameters, required permissions and response schemas.

Create an API key in Settings, then Your sign-in & privacy, then API keys, and give it only the permissions your task needs. A key belongs to your account and has the same access you do. To let an AI assistant or Home Assistant use your library, connect it as a connected app instead: it asks you first and never gets your key.

Use the CLI that matches your Frameleaf server release: its published CLI container image at the same version, or a build of the matching source release:

Terminal window
pnpm install --frozen-lockfile
pnpm --filter @frameleaf/sdk build
pnpm --filter @frameleaf/cli build
node packages/cli/dist/index.js --help

The examples below use the installed frameleaf command. For a source build, replace it with node packages/cli/dist/index.js.

  1. Set FRAMELEAF_INSTANCE_URL to your server address followed by /api, such as https://photos.example.com/api.
  2. Set FRAMELEAF_API_KEY through your shell’s secret or environment facility.
  3. Check the connection:
Terminal window
frameleaf server-info

Prefer to sign in once? frameleaf login URL API-KEY saves your credentials in ~/.config/frameleaf/auth.yml, and frameleaf logout removes them. Keep real keys out of your shell history. To store the configuration in a private folder of your choice, set FRAMELEAF_CONFIG_DIR.

Terminal window
# Preview the work first.
frameleaf upload --dry-run --recursive ./Photos
# Upload a folder and its subfolders.
frameleaf upload --recursive ./Photos
# Create an album for each folder.
frameleaf upload --album --recursive ./Photos
# Put the upload into a named album.
frameleaf upload --album-name "Summer holiday" --recursive ./Photos
# Leave matching paths out.
frameleaf upload --ignore '**/Raw/**' --recursive ./Photos

The CLI checks for duplicates before uploading, so you can rerun it on the same folder safely. Hidden files and folders are skipped unless you add --include-hidden. Add --watch to keep watching a folder and upload new files as they arrive. --skip-hash skips the client’s pre-upload checksum check; the server still catches duplicates as they arrive.

Option Environment variable Purpose
--recursive FRAMELEAF_RECURSIVE Include subfolders.
--ignore <pattern> FRAMELEAF_IGNORE_PATHS Skip matching paths.
--include-hidden FRAMELEAF_INCLUDE_HIDDEN Include hidden paths.
--album FRAMELEAF_AUTO_CREATE_ALBUM Create albums from folders.
--album-name <name> FRAMELEAF_ALBUM_NAME Use one named album.
--visibility <value> FRAMELEAF_VISIBILITY Set timeline, archive, hidden or locked.
--concurrency <number> FRAMELEAF_UPLOAD_CONCURRENCY Limit simultaneous uploads.
--dry-run FRAMELEAF_DRY_RUN Preview without uploading.
--watch FRAMELEAF_WATCH_CHANGES Watch for new files.
--json-output FRAMELEAF_JSON_OUTPUT Print upload results as JSON; diagnostic output may also be present.

Run frameleaf upload --help to see every option in your installed version. Leave --skip-hash off when you use --dry-run.

frameleaf migrate copies an account’s library from one Frameleaf server to another, and keeps a local ledger so it can pick up where it left off. It needs that account’s API key on each server. Move to a new server walks you through it, and explains how it differs from restoring a whole installation’s database.

frameleaf locked works with files protected by Locked encryption, so you can open them without the server. That guide has the steps.

The server container includes frameleaf-admin. For a manual deployment using the supplied container name:

Terminal window
docker exec -it frameleaf_server frameleaf-admin help

Manager installations generate their own container names, so find the application container in Manager or with docker ps first. See Server commands for account recovery, setup and maintenance tasks.