filesnap

filesnap is a command-line tool for managing files and directories.

Motivation

filesnap was born out of necessity in a professional production environment. Dealing with massive directory structures and thousands of assets manually is error-prone and slow.

I built this tool to:

• Automate Database Seeding: Quickly export entire folders of images or assets into structured formats (CSV, JSON) to sync filenames with database records.
• Bulk Audit: Count and scan files by extension.
• Smart Cleanup: Safely prune specific file types or filenames across nested directories using --dry-run to prevent accidental data loss.

Installation

you can install it globally using uv by astral

uv tool install filesnap

or with pip

pip3 install filesnap

Commands

filesnap scan

Scans all the files in the path.

Argument	Description	Default
path	Path to scan	Current directory

Option	Alias	Description
--recursive	-r	Recursive search.
--pretty	-p	Pretty print the output in a table.
--exclude		Exclude files/directories from scanning.
--ext	-e	Scan only files with these extensions.

Example:

filesnap scan ./src --recursive --ext .py --exclude __pycache__

filesnap count

Counts all the files by extension in the path selected.

Argument	Description	Default
path	Path to count	Current directory

Option	Alias	Description
--recursive	-r	Recursive search.
--exclude		Exclude files/directories from counting.

Example:

filesnap count ./assets --recursive

filesnap clean

Cleans the content of a path.

Argument	Description
path	Path to clean

Option	Alias	Description
--recursive	-r	Recursive cleaning.
--contain	-c	Clean only files containing this string.
--ext	-e	Clean only files with these extensions.
--exclude		Exclude files/directories from cleaning.
--force	-f	Force deletion without confirmation.
--dry-run	--dry	Simulate cleaning without deleting files.

Example:

filesnap clean ./temp --ext .log --force

filesnap export

Exports the filenames to a file.

Argument	Description
path	Path to scan for filenames

Option	Alias	Description
--type	-t	The type of file to export to (e.g., txt, csv, json).
--recursive	-r	Recursive scanning.
--output	-o	The output file name.
--format	-f	The format of the output.
--column	-c	The column to export (defaults to file_name).

Example:

filesnap export ./images --type json --output manifest.json --recursive

filesnap compress

Compresses all the images in the path selected with different formats.

Argument	Description
source_path	Path to images to compress
destination_path	Path to save compressed images

Option	Alias	Description
--current-format	-f	The format of the images to compress.
--new-format	-t	The format to convert the images to.
--quality	-q	The quality of the compressed images (60-100).

Example:

filesnap compress ./raw ./optimized -f png -t jpg --quality 85