Command Line Tool

photoq CLI

Sync your gallery from the command line. Pull photos to your local machine or push local folders to the server — fast, scriptable, and secure.

Download for Windows All Platforms

Downloads

Choose Your Platform

Self-contained executables — no runtime required.

Windows

x64 Download

macOS

Intel (x64) Download

macOS

Apple Silicon (ARM64) Download

Linux

x64 Download

Quick Start

Getting Started

Up and running in three steps.

Download & Extract

Download the zip for your platform and extract it to a folder of your choice. The archive contains photoq and appsettings.json.

Configure

Edit appsettings.json with your API URL, tenant, account, and local folder. Then run photoq encrypt to secure your password.

Sync

Run photoq pull to download your gallery locally or photoq push to upload local photos to the server.

Documentation

CLI Reference

Complete command documentation for photoq.

`photoq pull`

Download photos and folder structure from the server to your local machine. Compares the remote gallery with your local folder and downloads new or updated files.

photoq pull [--tenant <SLUG>] [--folder <PATH>] [--url <API_URL>]
            [--account <NAME>] [--password <PASSWORD>]
            [--nodelete] [--nofiles] [--emptyfolders] [--filter <PATTERNS>]

Option	Description
`--tenant <SLUG>`	Tenant slug to sync. Falls back to config, then interactive prompt.
`--folder <PATH>`	Local destination folder for downloaded files.
`--url <API_URL>`	Base URL of the gallery REST API.
`--account <NAME>`	Account email or username for authentication.
`--password <PASSWORD>`	Password (supports `ENCRYPTED:` values).
`--nodelete`	Only add and update — never delete local files.
`--nofiles`	Sync folder/album structure only, skip file transfers.
`--emptyfolders`	Include empty folders (skipped by default).
`--filter <PATTERNS>`	Wildcard file filters, e.g. `.jpg .png`.

Examples

# Pull entire tenant to local folder
photoq pull --tenant mysite --folder ~/photos

# Pull without deleting local files that were removed from server
photoq pull --nodelete

# Pull only JPEG files
photoq pull --filter "*.jpg"

`photoq push`

Upload photos and folder structure from your local machine to the server. Compares your local folder with the remote gallery and uploads new or updated files.

photoq push [--tenant <SLUG>] [--folder <PATH>] [--url <API_URL>]
            [--account <NAME>] [--password <PASSWORD>]
            [--nodelete] [--nofiles] [--emptyfolders] [--filter <PATTERNS>]

Option	Description
`--tenant <SLUG>`	Tenant slug to sync. Falls back to config, then interactive prompt.
`--folder <PATH>`	Local source folder to upload from.
`--url <API_URL>`	Base URL of the gallery REST API.
`--account <NAME>`	Account email or username for authentication.
`--password <PASSWORD>`	Password (supports `ENCRYPTED:` values).
`--nodelete`	Only add and update — never delete remote files.
`--nofiles`	Sync folder/album structure only, skip file transfers.
`--emptyfolders`	Include empty folders (skipped by default).
`--filter <PATTERNS>`	Wildcard file filters, e.g. `.jpg .png`.

Examples

# Push local photos to server
photoq push --tenant mysite --folder ~/photos

# Push only new files, never delete from server
photoq push --nodelete

# Push folder structure only (no file transfers)
photoq push --nofiles

`photoq ls`

List containers and files in the remote gallery via the REST API. Navigate the gallery hierarchy by specifying a path.

photoq ls [PATH] [--url <API_URL>] [--account <NAME>]
          [--password <PASSWORD>] [--detail]

Option	Description
`[PATH]`	Gallery path to list. Omit for root, use `tenant/folder/album` to drill down.
`--url <API_URL>`	Base URL of the gallery REST API.
`--account <NAME>`	Account email or username for authentication.
`--password <PASSWORD>`	Password (supports `ENCRYPTED:` values).
`--detail`	Show extended details (quota, visibility, age restriction).

Examples

# List all tenants
photoq ls

# List contents of a tenant
photoq ls mysite

# List album contents with full details
photoq ls mysite/vacation/summer-2026 --detail

`photoq encrypt`

Encrypt the plaintext password stored in appsettings.json. The encrypted value is written back in place, prefixed with ENCRYPTED:. All other commands transparently decrypt it at runtime.

photoq encrypt

Run this once after setting your password in appsettings.json to avoid storing it in plaintext.

Setup

Configuration

Configure defaults so you don't have to type them every time.

The appsettings.json file ships alongside the photoq executable. Edit it to set your defaults:

{
  "Defaults": {
    "ApiUrl": "https://gallery.example.com/",
    "Tenant": "mysite",
    "Folder": "/home/user/photos",
    "Account": "user@example.com",
    "Password": "your-password-here",
    "Filter": []
  }
}

Key	Description
`ApiUrl`	Base URL of your gallery's REST API.
`Tenant`	Default tenant slug used by `pull` and `push`.
`Folder`	Default local folder path for sync operations.
`Account`	Account email or username for API authentication.
`Password`	Password in plaintext or encrypted form. Run `photoq encrypt` after setting.
`Filter`	Default file filter patterns (e.g. `[".jpg", ".png"]`). Empty array means all supported types.

Option Resolution Order

When a value is needed, photoq resolves it in this order:

Command-line flag — highest priority, e.g. --tenant mysite
appsettings.json — the Defaults section
Interactive prompt — asks you at runtime if still missing

Ready to Sync?

Download photoq and start managing your gallery from the terminal.

Download for Windows All Platforms