A plugin-driven photographer workflow engine for macOS and Linux.
Piqley processes exported photos and publishes them to any service with an API or CLI: Ghost, WordPress, Squarespace, social media, or your own custom workflow.
Want to export full-resolution photos with all metadata but strip GPS and private tags before publishing? Piqley can do that. Want to use keyword metadata and IPTC tags to draft a social media post without typing anything, #AnalogFilmIsNotDead? Piqley can do that. Want to use different hashtags for different services? Piqley can do that. Under the hood, everything is a plugin. Mix and match plugins into a pipeline that fits your workflow.
It works with any photo editor that exports to a folder (Lightroom, Capture One, Apple Photos, darktable, RawTherapee, etc.) and pairs well with Hazel on macOS or any folder-watching automation for a fully hands-off workflow.
swift build -c release
cp .build/release/piqley /usr/local/bin/piqley# Interactive setup: configures plugins and secrets
piqley setup
# Process a folder of exported photos
piqley process /path/to/exported/photos| Command | Description |
|---|---|
piqley setup |
Interactive configuration and plugin setup |
piqley process [workflow] <path> |
Process and publish photos (workflow name required when multiple exist) |
piqley plugin list |
List all installed plugins with active/inactive status |
piqley plugin setup [name] |
Configure a specific plugin (use --force to re-run setup) |
piqley plugin init [id] [name] |
Create a new declarative-only plugin interactively |
piqley plugin create <dir> --identifier <id> |
Scaffold a new plugin project from an SDK template |
piqley plugin install <source> |
Install a .piqleyplugin from a file path, URL, or git repo (--force to overwrite) |
piqley plugin update <source> |
Update an installed plugin from a file path, URL, or git repo |
piqley plugin uninstall <id> |
Uninstall a plugin by identifier |
piqley plugin edit [id] |
Edit rules for a mutable plugin (lists mutable plugins if id omitted) |
piqley workflow list |
List all workflows |
piqley workflow edit [name] |
Edit a workflow interactively (lists all workflows if name omitted) |
piqley workflow create [name] |
Create a new workflow |
piqley workflow clone <src> <dst> |
Clone an existing workflow |
piqley workflow delete <name> |
Delete a workflow (--force to skip prompt) |
piqley workflow open <name> |
Open a workflow file in your editor |
piqley workflow config [workflow] <plugin> |
Set per-plugin config overrides for a workflow |
piqley workflow add-plugin <workflow> <plugin> <stage> |
Add a plugin to a workflow stage |
piqley workflow remove-plugin <workflow> <plugin> <stage> |
Remove a plugin from a workflow stage |
piqley workflow rules [workflow] <plugin> |
Interactive rule editor for a plugin's declarative metadata rules |
piqley workflow command [workflow] <plugin> |
Edit binary command configuration for a plugin's stages |
piqley secret set <plugin> <key> |
Store a secret in the macOS Keychain |
piqley secret delete <plugin> <key> |
Remove a secret from the Keychain |
piqley secret prune |
Remove orphaned secrets not referenced by any config or workflow |
piqley clear-cache |
Clear plugin execution logs (--plugin <name> for a specific plugin) |
piqley uninstall |
Remove all piqley configuration and plugins (--force to skip prompt) |
--dry-run- Preview actions without uploading--debug- Enable debug output from plugins--delete-source-contents- Delete the contents of the source folder after a successful run--delete-source-folder- Delete the source folder and its contents after a successful run--overwrite-source- Overwrite source images with processed versions after a successful run--non-interactive- Skip interactive prompts; drop invalid rules with warnings--lock-timeout <seconds>- Seconds to wait for another instance to finish (default: 600)
Piqley's core is a lightweight orchestrator. All real work (image processing, uploading, scheduling) is handled by plugins running as isolated subprocesses. Piqley copies images into a temporary folder before the pipeline runs, plugins operate on those copies, and the processed results are copied back over the originals when the pipeline completes. The temp folder is automatically cleaned up.
A plugin is a directory inside ~/.config/piqley/plugins/<plugin-name>/ containing a manifest.json and an executable. Write plugins in any language: Swift, Python, Go, Bash, or anything else that can read JSON from stdin and write JSON lines to stdout.
~/.config/piqley/plugins/my-plugin/
├── manifest.json # Declarative: config schema, dependencies, supported platforms
├── stage-pre-process.json # Rules for pre-process hook
├── stage-post-process.json # Rules for post-process hook
├── data/ # Plugin working directory
└── bin/ # Plugin executables (platform-specific at build time, flattened on install)
Plugins support multiple platforms. A .piqleyplugin package can bundle binaries for macos-arm64, linux-amd64, and linux-arm64. When you install a plugin, piqley copies only the binaries for your platform.
Plugins register for hooks in a pipeline. The default stages are:
| Hook | Purpose |
|---|---|
pre-process |
Modify images before processing (e.g. watermarking) |
post-process |
Modify images after processing (e.g. resize, metadata) |
publish |
Upload or distribute processed images |
post-publish |
Clean up, notify, or log after publishing |
Two lifecycle stages (pipeline-start, pipeline-finished) run automatically and cannot be removed. You can also add custom stages and reorder the pipeline via the workflow editor.
Workflows are stored in ~/.config/piqley/workflows/ as named JSON files. Each workflow defines its own pipeline. piqley setup creates a default workflow.
{
"name": "default",
"displayName": "Default Workflow",
"description": "Main photo processing workflow",
"schemaVersion": 1,
"pipeline": {
"pre-process": ["privacy-strip", "ghost-tagger"],
"publish": ["ghost-publisher"]
}
}Plugins communicate over stdin/stdout using one of two protocols:
JSON protocol (default). Piqley sends a JSON object on stdin and the plugin streams JSON lines back:
{"type": "progress", "message": "Uploading photo.jpg..."}
{"type": "imageResult", "filename": "photo.jpg", "status": "success"}
{"type": "result", "success": true, "error": null}Pipe protocol. Context is passed via environment variables and stdout/stderr are forwarded directly. Exit code determines success.
| Variable | Description |
|---|---|
PIQLEY_IMAGE_FOLDER_PATH |
Directory containing images to process |
PIQLEY_HOOK |
Current pipeline stage name |
PIQLEY_DRY_RUN |
"1" when dry run is active, "0" otherwise |
PIQLEY_DEBUG |
"1" when debug mode is active, "0" otherwise |
PIQLEY_IMAGE_PATH |
Path to the current image (single-image mode) |
PIQLEY_PIPELINE_RUN_ID |
Unique identifier for this pipeline run |
PIQLEY_SECRET_* |
Secret values (e.g. PIQLEY_SECRET_API_KEY) |
PIQLEY_CONFIG_* |
Config values (e.g. PIQLEY_CONFIG_BASE_URL) |
Example plugin using the pipe protocol:
#!/bin/bash
# Resize images using ImageMagick
for img in "$PIQLEY_IMAGE_FOLDER_PATH"/*.jpg; do
[ "$PIQLEY_DRY_RUN" = "1" ] && echo "Would resize: $img" && continue
magick "$img" -resize 2048x2048\> "$img"
echo "Resized: $(basename "$img")"
doneThe piqley plugin SDK provides a Swift library for building plugins. You can also skip the SDK entirely and write a plain executable in any language. See the SDK README for the full manifest schema and protocol details.
- macOS 15+ or Linux
- Swift 6.0+ toolchain
swift build
swift test