###################
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.

.. contents:: On this page
   :local:
   :depth: 2

Quick Start
===========

.. code-block:: console

   # 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**

.. code-block:: console

   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.

.. code-block:: console

   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``.

.. code-block:: console

   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.

.. code-block:: console

   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
=================

.. list-table:: Recursive defaults by strategy
   :header-rows: 1
   :widths: 40 40

   * - 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:

.. code-block:: bash

   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:

.. code-block:: bash

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