# API and command-line uploads

Source: https://frameleaf.app/docs/admin/api-and-cli/

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](https://frameleaf.app/docs/api/overview/); its [endpoint reference](https://frameleaf.app/docs/api/reference/) lists parameters, required permissions and response schemas.

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

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

## Connect

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:

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

## Upload files and folders

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

:::caution[Keep your originals]
`--delete` and `--delete-duplicates` remove files from your computer. Leave them off for everyday imports. If you do use them, keep a separate backup and check your library in Frameleaf first.
:::

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

`frameleaf locked` works with files protected by [Locked encryption](https://frameleaf.app/docs/using/locked-encryption/), so you can open them without the server. That guide has the steps.

## Administrator commands

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

```bash
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](https://frameleaf.app/docs/admin/server-commands/) for account recovery, setup and maintenance tasks.
