Skip to content
FileMayorby Chevza
Download
Documentation · CLI reference

Fifteen verbs.

The CLI is the canonical surface. Every command takes --json for shell integration. Requires Node.js ≥ 20.

npm install -g filemayor
The Curative Triad · core verbs

Diagnose, plan, apply.

  1. scan

    filemayor scan <dir>

    Recursive file inventory. Categorizes by extension, surfaces duplicates and bloat. Read-only — never moves a file. Output is machine-friendly with --json.

    filemayor scan ~/Downloads --json | jq ".duplicates"

  2. explain

    filemayor explain <dir>

    AI health diagnosis. Returns a 0–100 score plus a plain-English issue list (screenshot clutter, dupe installers, stale archives). Read-only.

    filemayor explain ~/Downloads

    Sends file metadata to the configured AI provider. No file contents.

  3. cure

    filemayor cure <dir> [--prompt "..."] [--para]

    Generate a curative plan. Proposes specific moves with rationale. Writes nothing — outputs the plan only. `--para` asks the AI to sort by actionability into the four PARA buckets. Apply with `filemayor apply` or discard.

    filemayor cure ~/Downloads --para

  4. apply

    filemayor apply

    Execute the most recent plan. Every move is journaled. Atomic per category — a failure in one category does not corrupt the others. Reversible with `filemayor undo`.

    filemayor apply

  5. undo

    filemayor undo [--list | --session <id> | --all]

    Reverse moves and deletions. Plain `undo` reverses the most recent session; `--list` shows undoable history; `--session <id>` reverses a specific past session; `--all` reverses everything. Restores trashed files too. Persists across crashes.

    filemayor undo --list
Tools

Direct operations.

  1. organize

    filemayor organize <dir> [--dry-run]

    Deterministic auto-organize. Sorts files into 12 smart categories (Code, Images, Archives, Documents, Configs, Media, etc.). No AI involved.

    filemayor organize ~/Downloads --dry-run

  2. para

    filemayor para <dir> [--archive-after <n>]

    Sort by actionability using the PARA method (Projects, Areas, Resources, Archives). Deterministic — labels every move with its reason, then apply with `filemayor apply`. No AI key needed.

    filemayor para ~/Documents

  3. clean

    filemayor clean <dir> [--yes]

    Remove junk: temp files, .DS_Store, Thumbs.db, .crdownload, node_modules artifacts, OS caches. Prompts before deletion unless --yes.

    filemayor clean /tmp --yes

  4. analyze

    filemayor analyze <dir>

    Deep directory intelligence. Surfaces top largest files, duplicate clusters, deep nests, file-age distribution, and bloat sources.

    filemayor analyze ~/Downloads

  5. duplicates

    filemayor duplicates <dir>

    Find duplicate files by content hash. Read-only.

    filemayor duplicates ~/Photos --json

  6. dedupe

    filemayor dedupe <dir>

    Remove duplicates safely — matched by content hash, not filename. Keeps the oldest copy; the rest go to FileMayor’s trash, journaled, so `filemayor undo` restores them.

    filemayor dedupe ~/Photos

  7. watch

    filemayor watch <dir> [--para]

    Live auto-organize. Monitors a folder; routes new arrivals to their correct homes in real-time. `--para` routes each new file into Projects / Areas / Resources / Archives by actionability — journaled, so undo works.

    filemayor watch ~/Downloads --para
Meta

Configuration and status.

  1. init

    filemayor init [--para]

    Create a `.filemayor.yml` config in the current directory. Defines categories, watch rules, AI provider, and locale. Use `--para` to scaffold the four PARA folders with a tuned config.

    filemayor init --para

  2. info

    filemayor info

    System info, version, AI provider connectivity, and journal location.

    filemayor info

  3. license

    filemayor license [activate|deactivate] [<key>]

    Everything is free — no license required. This command manages an optional license key, retained for organizations that need a formal license record. Validates locally with a 30-day offline grace period.

    filemayor license activate FM-XXXX-XXXX

Exit codes

  • 0 — success
  • 1 — generic error
  • 2 — invalid arguments
  • 3 — Doctrine block (Guardrail, Validator, or Security layer refused)
  • 5 — AI provider unreachable (with --offline-fail)