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.
Before you begin
Section titled “Before you begin”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:
pnpm install --frozen-lockfilepnpm --filter @frameleaf/sdk buildpnpm --filter @frameleaf/cli buildnode packages/cli/dist/index.js --helpThe examples below use the installed frameleaf command. For a source build, replace it with node packages/cli/dist/index.js.
Connect
Section titled “Connect”- Set
FRAMELEAF_INSTANCE_URLto your server address followed by/api, such ashttps://photos.example.com/api. - Set
FRAMELEAF_API_KEYthrough your shell’s secret or environment facility. - Check the connection:
frameleaf server-infoPrefer 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.
Upload files and folders
Section titled “Upload files and folders”# 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 ./PhotosThe 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.
Move between Frameleaf servers
Section titled “Move between Frameleaf servers”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.
Open encrypted Locked files
Section titled “Open encrypted Locked files”frameleaf locked works with files protected by Locked encryption, so you can open them without the server. That guide has the steps.
Administrator commands
Section titled “Administrator commands”The server container includes frameleaf-admin. For a manual deployment using the supplied container name:
docker exec -it frameleaf_server frameleaf-admin helpManager 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.
© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.
