CLI reference¶

photo-tagger runs as a single command, photo-tagger, built with cyclopts. Its flags are grouped into logical option groups; this page documents every flag, its default, the matching environment variable (or - when there is none), and what it does.

Any flag you pass on the command line overrides the corresponding config-file value and environment-informed default. See Configuration for the full precedence rules and TOML layout.

Commands¶

Running photo-tagger with image inputs tags them (the default command). Two subcommands exist:

doctor accepts --provider, -m/--model, -u/--url, and -k/--api-key (same meanings as below) and honors the same config file and environment variables. Run it first when a tagging run will not start:

$ photo-tagger doctor --provider lmstudio --model qwen/qwen3-vl-30b
photo-tagger 0.5.0 environment check

  OK    ExifTool: /usr/bin/exiftool
  OK    Model 'qwen/qwen3-vl-30b' on lmstudio: available at http://localhost:1234/v1

All checks passed.

Input and scanning¶

-i/--input is required and repeatable: pass it once per file or directory you want to process.

Provider¶

The provider group selects the backend and how to reach it. Prefer the API-key environment variables over --api-key so the key never lands in your shell history.

Inference¶

These flags tune sampling and the image sent to the model. Lower temperature and a frequency penalty keep the output focused; the JPEG settings control how much detail the model sees.

Output¶

The output group decides what metadata is written and where. By default photo-tagger writes an XMP sidecar next to each image and leaves the original untouched.

Filter¶

Filters narrow the resolved batch before any model call. Timestamps use ISO 8601, such as 2024-01-01 or 2024-01-01T14:30; naive timestamps use local time.

Log¶

photo-tagger writes a timestamped log file and mirrors messages to stderr, so stdout stays clean for --json output.

Display¶

The display group controls the progress bar and machine-readable output.

Artifacts¶

The artifacts group points at side files: a custom prompt, a run summary, a per-photo CSV report, a result cache, and a lock.

CSV report¶

Where --summary-file writes one JSON object for the whole run and --json streams NDJSON to stdout, --csv-file writes a spreadsheet-friendly table with one row per photo. It is the single file that gathers everything extracted and computed for each image:

• filename, file, status
• title, description, keywords (the keywords actually written), hierarchical_keywords
• existing_keywords (what was already on the file)
• camera_model, lens_model, capture_date, gps_position, city, country (read EXIF)
• input_tokens, output_tokens, total_tokens, seconds, from_cache, retry

Multi-value cells (the keyword lists) are joined with a semicolon and a space. Rows are flushed as each photo completes, so interrupting the run with Ctrl-C still leaves a complete, openable CSV of the work done so far. --csv-file and --json can be used together; both observe every photo. A --dry-run still fills the report, which makes it handy for previewing a batch before writing any metadata.

Skipping and resuming¶

Three flags cooperate to skip work you have already done and to resume a run that stopped partway through:

• --skip-from PATH reads a list of filenames (one per line, # comments allowed) and drops any matching files from the batch before processing starts.
• --append-to-skip-file PATH appends each successfully tagged filename to PATH as the run progresses, creating the file if it does not exist.
• --skip-tagged inspects each file's existing metadata and skips anything that already has keywords, a title, or a description (in the image or its XMP sidecar). Use it when you want the skip decision to come from the files themselves rather than from a list.

For resume-on-failure, pass the same path to both --skip-from and --append-to-skip-file. The first run appends every success to the file; if the run dies partway through, re-running with the same arguments reads that file back through --skip-from and continues from where it left off, without re-tagging the photos that already succeeded.

See Recipes for runnable resume and skip examples.