Skip to content
FileMayorby Chevza
Download
Documentation · CLI reference

Fourteen 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 "..."]

    Generate a curative plan. Proposes specific moves with rationale. Writes nothing — outputs the plan only. Apply it with `filemayor apply` or discard.

    filemayor cure ~/Downloads --prompt "organize by type"

  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 [--all]

    Reverse moves. Without flags, reverses the most recent operation. `--all` reverses the entire session. Persists across crashes.

    filemayor undo --all
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. 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

  3. analyze

    filemayor analyze <dir>

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

    filemayor analyze ~/Downloads

  4. duplicates

    filemayor duplicates <dir>

    Find duplicate files by content hash. Read-only.

    filemayor duplicates ~/Photos --json

  5. dedupe

    filemayor dedupe <dir>

    Remove duplicates safely. Keeps the canonical copy (oldest, or matching a heuristic), trashes the rest. Journaled.

    filemayor dedupe ~/Photos

  6. watch Pro

    filemayor watch <dir>

    Live auto-organize. Monitors a folder; routes new arrivals to their correct homes in real-time. Pro feature.

    filemayor watch ~/Downloads
Meta

Configuration and status.

  1. init

    filemayor init

    Create a `.filemayor.json` config in the current directory. Defines categories, watch rules, AI provider, and locale.

    filemayor init

  2. info

    filemayor info

    System info, version, license status, AI provider connectivity, journal location.

    filemayor info

  3. license

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

    Activate or deactivate a Pro license. 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)
  • 4 — license required for Pro feature
  • 5 — AI provider unreachable (with --offline-fail)