organize

fialr organize <target> [options]

Run the complete organize pipeline: scan, classify, plan, and optionally execute. Dry-run by default. To execute, pass both --execute and --reviewed.

---

Arguments

Argument	Description
target	Directory to organize (required)

Options

Option	Description
--execute	Execute the plan (not just dry-run)
--reviewed	Confirm that execution is approved (required with --execute)
--jobs-dir PATH	Directory for job artifacts (default: .fialr/jobs)
--sensitivity-rules PATH	Path to sensitivity.yaml (default: config/sensitivity.yaml)
--schema PATH	Path to schema.yaml (default: config/schema.yaml)

---

What it does

Dry-run (default)

Without --execute, organize runs the scan, classify, and plan phases only. This is identical to running fialr plan <target>. No files move. The output shows what would happen.

Execution

With --execute --reviewed, the executor processes each operation in the plan:

1. Pre-move hash verification — recompute the BLAKE3 hash of the source file and compare against the manifest
2. Record provenance — write the original path and original name to XATTRs and SQLite before any modification
3. Move/rename — execute the file operation
4. Post-move hash verification — recompute the BLAKE3 hash at the destination and confirm it matches
5. Log — record the operation in the append-only audit ledger

The --reviewed flag is mandatory. The executor refuses to run without it. This is a deliberate friction point: someone must confirm they have read the plan.

Checkpoint and resume

The executor writes a checkpoint after every N operations (configurable in fialr.toml under [inventory].checkpoint_interval, default: 50). If the process is interrupted, restarting it resumes from the last checkpoint. No operations are repeated. No data is lost.

Job artifacts

Every execution creates a job directory:

.fialr/jobs/{YYYY-MM-DD}_{job-name}_{uuid}/
  manifest.json      # pre-execution file state
  plan.csv           # the operations executed
  log.json           # append-only operation log
  report.md          # human-readable summary
  checkpoint.json    # last completed operation index

Rename engine

The rename engine applies the naming convention: YYYY-MM-DD_[entity]_[descriptor]_[version].[ext]. It derives date, entity, and descriptor tokens from file metadata, path components, and enrichment data. Generic names (scan001, untitled, document, copy-of) are rejected and replaced with meaningful tokens where possible.

---

Output

Dry-run:

organize ~/Documents

  SCAN      847 files (2.3s)
  CLASSIFY  847 files (0.1s)
  PLAN      847 operations (0.3s)
────────────────────────────────────────────────────────
     moves  812
   renames  743
     total  2.7s

Execution:

organize ~/Documents --execute --reviewed

  SCAN      847 files (2.3s)
  CLASSIFY  847 files (0.1s)
  PLAN      847 operations (0.3s)
  EXECUTE   812 moves (4.1s)
  VERIFY    812 files (1.8s)
────────────────────────────────────────────────────────
   executed  812
    skipped  35
     errors  0
      total  8.6s

---

Examples

# Dry-run the full pipeline
fialr organize ~/Documents

# Execute for real
fialr organize ~/Documents --execute --reviewed

# Specify a custom jobs directory
fialr organize ~/Documents --execute --reviewed --jobs-dir ./jobs

---

See also

• Reorganization guide — step-by-step walkthrough
• Job Execution Model — how jobs work
• plan — generate a plan without the execution step