Live/cli/

sortmoments CLI view.

Run Sort Moments without the GUI. Validate jobs, control paths, tune thresholds, configure model execution, and automate local-only photo sorting from a terminal.

CLI status: usable from source.

The terminal workflow stays in the header because it is the safer path right now. The Python package remains marked coming soon until the PyPI release is real.

Set up from source

The CLI view is the repo-based no-GUI workflow. It is separate from the PyPI library package: clone the project, install runtime dependencies, then run sortmoments_cli.py.

git clone https://github.com/DarthAmk97/SortMoments.git
cd SortMoments
python -m pip install -r requirements.txt
python sortmoments_cli.py --help

Want the packaged Python API later? See the coming-soon package notes.

Dry-run first

Dry-run validates paths, counts supported images, prints the processing plan, and does not import/load the model stack.

python sortmoments_cli.py organize D:/photos/family --output-folder D:/sorted/family --dry-run

Core commands

Both forms work from the source wrapper. The explicit organize verb is recommended for docs and scripts.

python sortmoments_cli.py organize D:/photos/family --output-folder D:/sorted/family --yes
python sortmoments_cli.py D:/photos/family --output-folder D:/sorted/family --yes
python sortmoments_cli.py organize D:/photos/family --dry-run

JSON config file

Use JSON for repeatable jobs. CLI flags override config values, so you can keep a base config and tweak one run.

{
  "input_folder": "D:/photos/family",
  "output_folder": "D:/sorted/family",
  "batch_size": 8,
  "workers": 4,
  "similarity_threshold": 0.58,
  "prefer_gpu": true,
  "keep_temp": true
}

python sortmoments_cli.py organize --config sortmoments-family.json --similarity-threshold 0.62 --yes

Library equivalent: configured organizer.

Folder and output options

FlagMeaningUse when

--output-folderFinal organized destination.You do not want output under source.

--temp-folderTemporary crops/embeddings folder.You want cache/debug files somewhere specific.

--overwriteDelete final output first.You are replacing a previous run.

--keep-tempKeep intermediate artifacts.You want to inspect crops or debug models.

Quality and grouping options

--min-face-size

Ignore faces below a pixel size. Raise this to avoid tiny background faces.

--min-confidence

Detection confidence floor from 0 to 1.

--blur-threshold

Reject blurry face crops. Lower for old/noisy images.

--similarity-threshold

Grouping strictness. Higher means fewer accidental merges.

Same fields in Python: SortMomentsConfig.

Model and performance options

--gpu / --cpu

Prefer GPU providers or force CPU-only execution.

--model-name

InsightFace model pack name passed into the default provider.

--det-size WIDTH HEIGHT

Detector input size. Smaller can be faster; larger can catch harder faces.

--batch-size

Images per batch.

--workers

Parallel image-loading workers.

python sortmoments_cli.py organize D:/photos/archive --cpu --det-size 512 512 --batch-size 4 --workers 2 --yes

Recipes

Preview a jobValidate folder, output path, and image count with no model load.Repeatable family archiveKeep a JSON config and override thresholds per trial.CPU-only laptop runForce CPU, smaller detector size, fewer workers.Planning custom models?Watch the coming-soon Python API for detector, embedder, and grouping hooks.

Exit codes and automation

CodeMeaningCommon cause

0SuccessDry-run or processing completed.

1User-correctable errorBad path, no images, invalid config.

2CancelledInteractive confirmation declined.

130InterruptedKeyboard interrupt.

CLI or Python API?

Use the CLI now when you need path and config control from shell scripts. Use the Python API later, once it ships, for model injection, custom grouping, app callbacks, or staged detection/grouping.

Python API overview Model swapping guide Provider protocols