metasweep — metadata inspector & cleaner

Privacy‑friendly CLI to inspect and strip hidden metadata from files. Transparent (see what’s inside), flexible policies (aggressive/safe/custom), and local‑only (no network).

Quick install (Linux only for now):

npm i -g metasweep
metasweep --help

Or run once without installing:

npx metasweep inspect photo.jpg

Features

• Multi-format: Images (EXIF/IPTC/XMP via Exiv2), PDFs (/Info), Audio (ID3/FLAC/Vorbis via TagLib), ZIP (comments/extra fields)
• Transparency: human-readable inspect output with risk highlights
• Flexible cleaning: --inspect, --strip, --safe, --custom
• Batch-friendly: works on files, globs, or directories
• Local & private: no telemetry, no network calls
• Reports: optional JSON output (--report file.json)
• Dry-run preview: show planned keep/drop with --dry-run

Install

Option 1: npm (Linux only)

• Downloads the prebuilt AppImage binary from GitHub Releases.
• Currently supports Linux x64.

# Global install
npm i -g metasweep
metasweep --help

# One-off usage
npx metasweep inspect file.jpg

Environment overrides:

• METASWEEP_GH_REPO=owner/repo → use a different GitHub repo.
• METASWEEP_DOWNLOAD_URL=URL → use a direct asset URL.

Option 2: Prebuilt packages

Check the Releases page for binaries:

https://github.com/ashmod/metasweep/releases

• Linux/macOS/Windows: tar.gz/zip archives with metasweep binary + policies.
• Linux AppImage: portable, runs without extra deps.

Example (Linux tar.gz):

tar -xzf metasweep-*.tar.gz
sudo install -m 0755 bin/metasweep /usr/local/bin/metasweep
sudo mkdir -p /usr/local/share/metasweep/policies
sudo cp -r share/metasweep/policies/* /usr/local/share/metasweep/policies/

Example (AppImage):

chmod +x metasweep-*.AppImage
./metasweep-*.AppImage --help

Option 3: Build from source

# Ubuntu
sudo apt update
sudo apt install -y cmake build-essential libexiv2-dev libtag1-dev zlib1g-dev

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

CLI

metasweep <command> [targets...] [options]

Commands:
  inspect     Show metadata summary (no changes)
  strip       Remove metadata according to policy
  explain     Describe risks & recommendations

Full CLI docs: https://github.com/ashmod/metasweep#cli-documentation

CLI Documentation

Commands

inspect - Inspect metadata

Show metadata summary without making changes.

metasweep inspect [OPTIONS] files...

Positionals:

• files: Files to inspect (required, multiple allowed)

Options:

• -v, --verbose: Verbose field listing (can be repeated for more verbosity)
• -r, --recursive: Recurse into directories
• --report TEXT: Write JSON report to file
• --format TEXT: Output format: auto, json, or pretty (default: auto)

strip - Strip metadata

Remove metadata according to the specified policy.

metasweep strip [OPTIONS] files...

Positionals:

• files: Files to strip (required, multiple allowed)

Options:

• --dry-run: Show plan without writing any files
• --in-place: Overwrite original files (no backup)
• -o, --out-dir TEXT: Output directory for cleaned files
• -r, --recursive: Recurse into directories
• --yes: Skip confirmation prompts
• --report TEXT: Write JSON report to file
• --format TEXT: Output format: auto, json, or pretty (default: auto)
• --safe: Use built-in safe policy (keeps Orientation/ICC/DPI, drops identifiers)
• --custom TEXT: Policy file (YAML/JSON)
• --keep TEXT: Keep specific field(s) (repeatable)
• --drop TEXT: Drop specific field(s) (repeatable)

explain - Explain risks for a file

Describe metadata risks and recommendations for a specific file.

metasweep explain [OPTIONS] file

Positionals:

• file: File to explain (required)

Options:

• -v, --verbose: Verbose field listing (can be repeated for more verbosity)

Examples

# Inspect an image
metasweep inspect photo.jpg

# Strip aggressively (default), write photo.cleaned.jpg
metasweep strip photo.jpg

# Safer policy (keeps Orientation/ICC/DPI)
metasweep strip --safe photo.jpg

# JSON report for a batch
metasweep inspect ./to-share -r --format json > report.json

Policies

• Aggressive (default): keeps only essential fields like Orientation and ColorProfile.
• Safe (--safe): keeps Orientation/ICC/DPI, drops identifiers like GPS, serials, authorship, software tags. Reference policy files: https://github.com/ashmod/metasweep/tree/main/policies

Privacy & Safety

• No network calls. Ever.
• Only metadata areas are read/rewritten. File content remains untouched.
• Atomic writes used where possible.

Links

• GitHub: https://github.com/ashmod/metasweep
• Issues: https://github.com/ashmod/metasweep/issues

License

See LICENSE.