CLI Reference

Sortium ships with a first-class sortium executable so you can prepare and apply move plans entirely from the terminal—ideal for servers, cron jobs, or scripted workflows.

Quick Start

# Install Sortium (and the CLI) from PyPI
pip install sortium

# Generate a recursive plan that sorts Downloads by file type
sortium plan type --source ~/Downloads --dest ~/Archive --recursive

# Execute the plan now or later
sortium apply --plan ~/Downloads/sortium_plan_type_20250101_101010.json

# Need to reverse it? Use the undo shortcut
sortium undo --plan ~/Downloads/sortium_plan_type_20250101_101010.json

# Export a snapshot of the directory tree for auditing
sortium tree --source ~/Downloads --output ~/downloads_structure.json

Subcommands

plan

Generate a JSON plan using one of the built-in strategies.

Usage

sortium plan <type|extension|date|regex> --source PATH [options]

Key options

• --dest: Folder where the categorized structure should live. Defaults to --source.

• --plan-output: Explicit path for the emitted plan JSON.

• --ignore: Repeated names to skip (e.g., --ignore node_modules .git).

• --recursive / --no-recursive: Toggle nested scans (defaults depend on strategy).

• --regex / --regex-file: Supply category=pattern pairs for the regex strategy.

• --folder-type: Repeat for each category when using the date strategy.

apply

Execute a previously generated plan.

sortium apply --plan PLAN.json [--dry-run] [--reverse]

• --dry-run validates the plan without moving files.

• --reverse moves files back to their original source_path entries.

undo

Convenient alias for sortium apply --reverse.

sortium undo --plan PLAN.json [--dry-run]

This is useful when you want an explicit rollback step in documentation or scripts.

tree

Export a directory snapshot as JSON so you can review structures or commit them alongside a plan.

sortium tree --source PATH [--output tree.json] [--ignore ...]

If --output is omitted the JSON is written next to PATH as sortium_tree.json.

Best Practices

• Version control your plans. Commit sortium_plan_*.json files so you can

  tell exactly what moved and when.

• Use ``–dry-run`` during reviews. It surfaces stale paths or collisions

  before anything touches disk.

• Pair with backups. The CLI is powerful; keeping regular backups (or using

  undo immediately after verifying results) closes the loop on safety.

Strategy Defaults

Recursive defaults by strategy

Strategy	Recursive by default?
type	No (set --recursive for nested folders)
extension	Yes
regex	Yes
date	No (scans only immediate category folders unless --recursive)

Automation Examples

Schedule a nightly archive:

0 2 * * * sortium plan type --source /data/incoming --dest /data/archive \
   --recursive --plan-output /data/plans/nightly.json && \
   sortium apply --plan /data/plans/nightly.json >> /var/log/sortium.log 2>&1

Validate in CI without moving files:

sortium plan regex --source ./artifacts \
    --regex Reports='.*\.csv$' Notebooks='.*\.ipynb$' \
    --plan-output ./artifacts/plan.json
sortium apply --plan ./artifacts/plan.json --dry-run