FolderManifest CLI

The FolderManifest CLI brings every feature of the desktop app to your terminal so you can automate the boring, prove the important, and clean up in bulk. Instead of clicking through the GUI, you run a command — and because each command has a stable exit code and optional JSON output, those commands drop straight into Windows Task Scheduler, batch files, and CI pipelines.

The CLI ships inside the desktop app and is available to trial and paid users (the same license as the GUI). It is not a separate install and is not published to a package manager — it lives in the app you already installed, and it runs whether the app window is open or closed.

Install & first run

Install FolderManifest, activate a trial or license, and the CLI is ready. Open any terminal and just type foldermanifest:

foldermanifest --version
foldermanifest --help

Every command follows the same shape: foldermanifest <command> [paths...] [options].

Quick start

Three commands cover most of what people reach for first:

# Create a manifest of a folder (Markdown, with SHA-256 checksums)
foldermanifest generate "C:\Projects\Photos"

# Verify a folder against a saved JSON manifest (great for Task Scheduler/CI)
foldermanifest verify "C:\Projects\Photos" --manifest photos.json

# Hash some files
foldermanifest checksum report.pdf invoice.xlsx

Create a manifest — generate

generate <dir> walks a folder, hashes every file, and writes a manifest: a complete, timestamped record of exactly what was there and what it contained. Think of it as a notarized photograph of a folder at a moment in time.

foldermanifest generate "C:\Photos" --format md,json --algo sha256 --out photos
# writes photos.md and photos.json

Prove nothing changed — verify

verify <dir> --manifest <file> compares a folder's current state to a saved manifest and tells you what drifted. It exits 0 when everything matches and 1 when anything was added, removed, or modified — so a one-line script can react.

foldermanifest verify "C:\Photos" --manifest photos.json

# Branch on the result in a script:
foldermanifest verify "C:\Photos" --manifest photos.json || echo "FILES CHANGED!"

Markdown manifests are read-only and rejected by verify — use .json or .html as the verify input.

Hash files — checksum

checksum <paths...> computes SHA-256 for files (and for files inside given folders). Add --json for machine output or --report for an HTML report.

foldermanifest checksum *.iso --json
foldermanifest checksum *.iso --report checksums.html

Reclaim storage — duplicates

duplicates <paths...> finds — and optionally cleans — duplicate files across the given files/folders by comparing contents, so it catches copies even when the filenames differ. (This is distinct from sheet-analyze/sheet-dedupe, which work on rows inside a spreadsheet.)

# Find duplicates in a folder
foldermanifest duplicates "C:\Downloads" --report dupes.html

# Find AND clean: move extra copies to the Recovery Bin (reversible)
foldermanifest duplicates "C:\Photos" --clean

Cleaning never hard-deletes — copies move to the Recovery Bin and can be restored anytime; each group always keeps one file.

Compare files & folders

compare-files <a> <b> compares two files and compare-folders <a> <b> compares two folders (added / removed / modified). Both exit 1 when they differ, so they gate scripts just like verify.

foldermanifest compare-files old.pdf new.pdf
foldermanifest compare-folders ".\backup" ".\live"

Inspect metadata — metadata

metadata <paths...> extracts metadata (MIME type, size, embedded fields) from files. Add --json to feed an inventory pipeline or --out to save it.

foldermanifest metadata photo.jpg song.mp3 --json
foldermanifest metadata photos/* --out metadata.json

Clean spreadsheets — sheet-dedupe & sheet-analyze

The spreadsheet commands are namespaced (sheet-) to keep them clearly separate from the file-level duplicates tool. They operate on rows and values inside a CSV/XLSX, not on files.

sheet-dedupe — remove or merge duplicate rows

It has two modes:

• Single file — one file + --key removes duplicate rows.
• Cross-source — two or more files are combined and deduped across all of them, matching the key columns by name.

# Single file — collapse repeats by Email, filling blanks from later rows
foldermanifest sheet-dedupe contacts.xlsx --key Email --action merge-fill-blanks --format xlsx

# Combine + dedupe across multiple files (key matched by column name)
foldermanifest sheet-dedupe list-a.csv list-b.csv list-c.csv --key Email --out master.csv --report dedupe.html

sheet-analyze — duplicate-value report (no changes)

Finds duplicate values across cells and reports them per column — so you can see which columns have repeated values before you change anything. Nothing is modified; run it first to understand your data. Limit it with --columns (optional — defaults to all columns), and note this uses --columns, not --key:

# All columns (default)
foldermanifest sheet-analyze contacts.xlsx --report duplicate-values.html

# Only specific columns
foldermanifest sheet-analyze contacts.xlsx --columns Email,Phone

On either spreadsheet command, --list-sheets prints an .xlsx file's worksheet names and exits (mirroring the app's worksheet picker) so you can pick the right --sheet:

foldermanifest sheet-analyze quarterly.xlsx --list-sheets

Recovery Bin — recovery

When the duplicate cleaner removes files (duplicates --clean here, or the app), they go to the Recovery Bin rather than being deleted outright — the same safety net the desktop app uses. The recovery commands manage that bin from the terminal, so you can undo a bulk cleanup or reclaim space without opening the GUI. Restores are reversible; nothing is hard-deleted until you empty it.

foldermanifest recovery list
foldermanifest recovery restore item-12 item-15
foldermanifest recovery restore --all

Retention period

Each item is kept for a set time before it is deleted automatically — 7, 30, 90 days, or never (default 30), configured in the app under Settings → Recovery. When an item is moved in, its expiry is removed date + retention. Expired items are auto-purged when the app starts; recovery purge does the same on demand, while recovery empty deletes everything regardless of expiry. A never retention keeps items until you restore or empty them.

Organize folders — organize

The No-Stress File Organizer, from the terminal. It plans first, applies only with your explicit approval, and can undo the entire operation — every move is journaled, destinations are never overwritten, and files stay on one volume (no copy-and-delete).

foldermanifest organize rules --json
foldermanifest organize plan "C:\Downloads" --target "C:\Downloads" --preset tidy-by-type --out plan.folderplan.json
foldermanifest organize apply plan.folderplan.json --yes
foldermanifest organize undo <operation-id> --yes

Rules are deterministic — ordered, first match wins, no AI required. Four built-in presets ship with the app (minimal-cleanup, tidy-by-type, media-by-date, consolidate-backups), and custom rule books are plain JSON with conditions (name, extension, type, size, dates) and destination templates like Media/{year}/{month}. The saved plan is the same format the desktop app's Organize page edits visually — plan in the terminal, review in the GUI, or vice versa. apply and undo refuse to run without --yes.

The rule book, in full

Each rule has a matchMode (all = every condition must hold, any = at least one), one or more match conditions, and an action (move into a folder, optionally renamed, or leave in place). A file matching no rule stays where it is — add a catch-all “types: all → Other” rule last to sweep up leftovers.

Tokens for destinations and filenames: {project}, {sourceFolder}, {relativePath}, {name}, {stem}, {ext}, {type}, {year}, {month}, {monthName}, {day}, {shortHash}.

{
  "schemaVersion": 1,
  "name": "My PDFs",
  "rules": [
    { "id": "pdfs", "name": "PDF documents", "enabled": true,
      "matchMode": "any",
      "match": { "extensions": ["pdf"] },
      "action": { "kind": "move", "destination": "PDF" } }
  ]
}

The desktop app's Organize page has a full visual rule editor — no need to write JSON by hand.

Output formats — and why each one matters

• Markdown (md) — branded, human- and AI-readable, and diffs cleanly in git. Because the brand and URL travel inside the file, an AI agent that ingests your manifest also ingests where it came from. Read-only — not a verify input.
• JSON (json) — the exact machine format. Use it for verify and for any tool or agent that parses manifests.
• HTML (html) — a rich, shareable human report. (CSV and PDF outputs were dropped.)

Every result command can also save where you choose: --report <file.html> for a formatted report (works for checksum, duplicates, metadata, compare-files, compare-folders, sheet-analyze, and sheet-dedupe) and --out <file.json> for the raw result, manifest, or cleaned spreadsheet.

Reproducible bulk with --config

Define a list of jobs once in a JSON file, then run them anytime. Each job takes the same option names as the equivalent flag, and the overall exit code is the worst (non-zero) result among the jobs — so one command can guard a whole runbook.

{
  "jobs": [
    { "cmd": "generate", "paths": ["C:\\Photos"], "format": "json", "out": "photos" },
    { "cmd": "generate", "paths": ["C:\\Docs"], "format": "md,json", "out": "docs" },
    { "cmd": "verify",   "paths": ["C:\\Photos"], "manifest": "photos.json" }
  ]
}

foldermanifest --config nightly.json

For a full walkthrough of scheduling this on Windows, see Automate folder verification with the FolderManifest CLI.

For AI agents (Claude Code, Codex, Cursor)

The CLI is built for coding agents: --help --json makes every command self-describing, output uses a stable { ok, data | error } envelope, exit codes are fixed, and anything destructive requires an explicit --yes. An agent can discover the whole surface without reading these docs:

foldermanifest --help --json            # name, version, capabilities
foldermanifest organize --help --json   # any command family
foldermanifest organize rules --json    # presets, conditions, tokens

Paste this prompt into your agent to organize a folder safely:

You have the FolderManifest CLI installed as `foldermanifest`.
It is self-describing: start with `foldermanifest --help --json`, then
`foldermanifest <command> --help --json` for any command. Always pass --json
and parse the { ok, data | error } envelope. Exit codes: 0 ok, 1 drift/error,
2 no license, 3 usage or missing approval. Never invent flags — discover them.

Task: organize the folder <FOLDER> safely.
1. foldermanifest organize rules --json    (discover presets and tokens)
2. foldermanifest organize plan "<FOLDER>" --target "<FOLDER>" \
     --preset tidy-by-type --out plan.folderplan.json --json
3. Read plan.folderplan.json. Require data.summary.conflicts == 0 — resolve
   conflicts by editing entries' relativeDestination, then re-check.
4. Show me the plan summary and WAIT for my explicit approval.
5. foldermanifest organize apply plan.folderplan.json --yes --json
   (record data.operationId — it is the undo key)
6. If I ask to revert:
   foldermanifest organize undo <operationId> --yes --json

Rules: never run apply or undo without my approval; never delete files
(the CLI cannot — it only moves within one volume and journals every step).

The same pattern works for every command family — swap the steps for generate + verify (integrity checks in CI), duplicates --clean (reversible cleanup via the Recovery Bin), or sheet-dedupe (spreadsheet row dedupe). The prompt also ships with a copy button in the desktop app's CLI tab.

Exit codes

Stable codes let Windows Task Scheduler and CI pipelines branch on the result:

Global options available on every command:

--json            Machine-readable JSON to stdout (scripting / agents)
--out <path>      Write the result to a custom file
--report <path>   Write an HTML report to a custom path
--config <file>   Run a batch of jobs from a JSON file (reproducible)
--quiet           Suppress the trial reminder line
--help            Show usage
--version         Show the app version

Trial & licensing

• While on trial, every run prints a one-line reminder to stderr: Trial: 5 days left — upgrade at https://foldermanifest.com (silence it with --quiet).
• When the trial ends (or no license is active), commands stop with exit code 2 and an upgrade notice. Your files are never modified in this case.
• A paid license removes the reminder. Activate once in the desktop app and the CLI picks up the same license automatically.

Troubleshooting

Frequently asked questions