Guide

Command Line

TinyOwl ships one macOS app and one executable. Opening TinyOwl starts the desktop interface. Invoking the executable with arguments runs headlessly, without a window, Dock activation, tray setup, or WebView.

Install the command

On first launch, TinyOwl offers to enable the CLI with one click. You can also install or uninstall it later from Settings → General → Command Line Tool.

Both options create ~/.local/bin/tinyowl as a symlink to the current app executable. They never use sudo, request a password, edit shell profiles, or replace an existing file or another application’s symlink.

For unattended setup, run the same installer from the app bundle:

/Applications/TinyOwl.app/Contents/MacOS/TinyOwl cli install

If ~/.local/bin is not already on PATH, TinyOwl shows the directory to add before tinyowl can be invoked by name.

To remove only the link owned by the current TinyOwl app:

tinyowl cli uninstall

Commands

tinyowl --version
tinyowl workflows list
tinyowl workflows list --json
tinyowl workflows show workflow-compress-only
tinyowl inspect ~/Pictures/example.png --json
tinyowl run workflow-compress-only ~/Pictures/example.png --output-dir ~/Pictures/optimized
tinyowl run "Resize & Upload" ~/Pictures/post-images --dry-run --json
tinyowl run workflow-compress-and-upload image.png --skip-upload --output-dir ./out

workflows list --json prints the workflows already saved in the desktop app. A trimmed example from a real run:

{
  "ok": true,
  "workflows": [
    { "id": "workflow-compress-only", "name": "Compress only" },
    { "id": "workflow-compress-and-upload", "name": "Compress and upload" },
    { "id": "workflow-resize-compress-and-upload", "name": "Resize then upload" }
  ]
}

Directories are scanned recursively in deterministic order. Symlinked directories are not followed.

JSON, dry run, and exit codes

--json writes exactly one JSON document to stdout. Diagnostics and human-readable progress go to stderr.

--dry-run describes overwrite, crop, upload, output, provider readiness, and license requirements without writing files or contacting storage. A trimmed real preview for the compress-only workflow:

{
  "ok": true,
  "dryRun": true,
  "plan": {
    "workflow": { "id": "workflow-compress-only", "name": "Compress only" },
    "inputCount": 1,
    "items": [
      {
        "path": "~/Pictures/TinyOwl-demo.png",
        "plannedOutputPath": "~/Desktop/zipic/73e34bef.png",
        "supported": true
      }
    ],
    "compression": { "quality": 75, "outputFormat": "original" },
    "license": { "authorized": true, "required": false }
  }
}

Exit codes are stable:

Code	Meaning
`0`	Success
`2`	Usage or configuration error
`3`	Authorization required
`4`	Confirmation required
`5`	Partial failure
`6`	Total execution failure
`7`	Ambiguous workflow name

Partial batches return per-file results and exit code 5.

Safety and licensing

A workflow that overwrites source files or crops images requires --yes.
--skip-upload runs the local resize and compression steps only.
One supported image follows TinyOwl’s free behavior. A batch requires the same valid signed license or trial used by the desktop app.

Privacy and credentials

The CLI reads the desktop app’s existing settings.json. It does not use Keychain, and it does not accept storage credentials as command-line arguments.

Workflow and provider output exposes readiness booleans. It never prints an Access Key, Secret Key, or Session Token. Provider errors are redacted before they reach stdout, stderr, or TinyOwl logs.