Verifiable Folder Archives from the Command Line

• →One command, three destinations: local / NAS, S3 / B2 / R2, Google Drive.
• →The report is the deliverable — one row per file with its SHA-256.
• →Partial runs are honest: exit 1 + a named list, never silent gaps.
• →Copy-only — the source is never modified or deleted.

Why a verifiable archive?

Most copy commands tell you they finished. Almost none tell you what actually arrived. A dropped network share, a file locked by another process, a path that was too long, a permission the run-as account didn't have — each one silently skips a file, and the destination looks complete. Weeks later you reach for the backup and the one file you needed isn't there.

The FolderManifest archive command closes that gap. It copies the folder and writes a manifest and report into the destination, one row per file with its SHA-256, plus a named list of anything it could not copy. The report is the artifact you attach to the ticket, commit next to the backup, or email to the auditor — proof of what arrived, not just proof that the command returned.

Archive to local storage or a NAS

The simplest case: copy a folder to a NAS mount, an external drive, or another directory. The report lands in the destination root.

foldermanifest archive "D:\Projects" --dest "N:\Backup\Projects" --json

Add --include-hidden to capture hidden files. The manifest is always SHA-256 — it is a verification hash, not a dedup hash, so crc32 is intentionally not offered here.

Archive to S3, B2, R2, or MinIO

For offsite backup, point archive at an S3-compatible bucket. Omit --s3-endpoint for AWS; set it for Backblaze B2, Cloudflare R2, Wasabi, or a self-hosted MinIO.

foldermanifest archive "/var/data" --dest-s3 --s3-bucket my-bucket \
  --s3-prefix "data/2026-08" \
  --s3-endpoint s3.us-west-004.backblazeb2.com \
  --s3-access-key KEY --s3-secret-key SECRET --json

The secret keys are saved to the OS keychain and referenced by an opaque handle — they never appear in the job file, logs, telemetry, or the report itself.

Archive from Google Drive

Archiving a departing employee's Drive is the canonical use case. Pass the folder ID (the long string in the Drive URL) with --source-drive. The first run opens your browser once to sign in; the token is then reused from the keychain.

foldermanifest archive --source-drive 1A2B3c... --dest "E:\Offboarding\Jane" --json

Google-native files (Docs, Sheets, Slides) have no bytes to download, so they are exported — by default to editable .docx/.xlsx/.pptx. Use --native-export office+pdf to keep both, or stub for a .url pointer when the Drive account is being kept. Forms and Sites that cannot be exported are recorded as skipped in the report so nothing disappears quietly. You can also copy to a Drive folder with --dest-drive <id>.

The report is the deliverable

Every run writes two files into the destination root: _archive-report.html (a readable summary with a per-file hash table) and _archive-report.csv (one row per file — path, size, SHA-256, status). Together they answer "what arrived, and how do I prove it?" without re-running anything.

With --json, the same numbers go to stdout for scripts and agents:

{ "status": "completed", "filesDone": 1284, "failures": 0,
  "bytes": 45678901, "convertedCount": 37, "skippedCount": 2 }

convertedCount counts Google-native files archived as conversions; skippedCount counts items discovery found but could not hand over as bytes (Forms, Sites, dead shortcuts). Both are 0 for a local source.

Exit codes & partial runs

A backup script needs one pass/fail signal. The exit code is it:

On a partial run (exit 1), rerun the same command. The journal records every finished file, so resume skips them and retries only what failed — no duplicate writes, no starting over on a 400 GB archive because one file was locked.

Where credentials live

S3 secret keys and Google tokens are stored in the operating system keychain (Windows Credential Manager, macOS Keychain, or the Linux secret store) and referenced by an opaque handle. The secret itself is resolved in-process at run time and never travels into job.json, the manifest, the report, logs, or telemetry. Telemetry from an archive run is bucketed counts only — never file names, paths, bucket names, prefixes, or account emails.

Drive needs a one-time browser sign-in the first time you use --source-drive / --dest-drive. The CLI runs on your desktop, so it reuses the same OAuth flow as the Safe Archive tab — there is no separate headless auth to configure.

Hand it to an AI agent

Because archive is self-describing (--help --json), returns a stable envelope, and never deletes the source, it is safe to delegate to coding agents like Claude Code, Codex, or Cursor. Paste this prompt to archive a folder with a report that proves what arrived:

You have the FolderManifest CLI installed as `foldermanifest`.
It is self-describing: start with `foldermanifest --help --json`. Always pass
--json and parse the { ok, data | error } envelope. Exit codes: 0 ok, 1 partial
(some files failed — named in the report) or error, 2 no license, 3 usage.
The report IS the deliverable: _archive-report.html / .csv land in the
destination with one row per file and its SHA-256.

Task: archive the folder <SRC> to <DEST> with proof of what arrived.
1. foldermanifest archive "<SRC>" --dest "<DEST>" --json
2. Parse the result. Report data.filesDone, data.bytes, and data.failures.
3. If data.failures > 0 (exit 1, partial): do NOT delete the source. Surface the
   destination's _archive-report.html and list the files that did not arrive.
4. If data.failures == 0 (exit 0): confirm every file arrived; the report is the
   receipt. Do not delete the source unless I explicitly ask afterward.

Rules: the CLI never deletes the source — never delete it on my behalf. For S3
add --dest-s3 --s3-bucket <b> --s3-access-key <k> --s3-secret-key <k> (and
--s3-endpoint for B2/R2/MinIO); for Drive add --source-drive <folderId>.

See the AI-agent section of the CLI docs for the full prompt library.