auto-toolkit-cli

A small, dependency-light CLI toolkit for everyday automation: organizing files, finding duplicates, bulk renaming, checking disk usage, scanning ports, resizing images, converting PDFs to audio, and firing off ad-hoc API requests — all from one command.

Install

pip install auto-toolkit-cli

Some commands need extra dependencies, installed as optional extras:

pip install "auto-toolkit-cli[images]"   # resize-images (Pillow)
pip install "auto-toolkit-cli[audio]"    # pdf2audio (pyttsx3, pdfplumber, pydub, tqdm)
pip install "auto-toolkit-cli[all]"      # everything

organize, duplicates, rename, disk-usage, portscan, and api work with the base install — no extras required.

Commands

Command	What it does
organize	Sort files into type-based folders (Images, Documents, etc.), with dry-run, undo, and interactive conflict handling
duplicates	Find duplicate files by content hash, optionally delete all but one copy
rename	Batch-rename files with a regex pattern, prefix/suffix, or sequence numbering — with undo
disk-usage	Report the largest folders and files under a directory
portscan	Multi-threaded TCP port scanner with JSON/CSV export
resize-images	Batch-resize images to fit within a max dimension
pdf2audio	Convert a PDF's text into an MP3 (or other format)
api	Send a GET/POST/PUT/DELETE request and save the response to a file

Run autotoolkit --help or autotoolkit <command> --help for full options.

Examples

# Preview how Downloads would be organized, then actually do it
autotoolkit organize ~/Downloads --dry-run
autotoolkit organize ~/Downloads
autotoolkit organize ~/Downloads --undo   # revert the last run

# Find duplicate photos, then delete the extras (keeping one copy each)
autotoolkit duplicates ~/Pictures
autotoolkit duplicates ~/Pictures --delete --dry-run
autotoolkit duplicates ~/Pictures --delete

# Rename IMG_001.jpg, IMG_002.jpg -> vacation_001.jpg, vacation_002.jpg
autotoolkit rename ~/Photos --pattern "IMG_" --replace "vacation_"

# What's eating disk space in this folder?
autotoolkit disk-usage ~/Videos --top 20

# Scan common ports on localhost
autotoolkit portscan localhost 1 1024 --verbose --output results.json --format json

# Resize a folder of images to fit within 1024px
autotoolkit resize-images --source ./photos --output ./photos_resized --size 1024

# Turn a PDF into an audiobook
autotoolkit pdf2audio book.pdf --output book.mp3

# Send a quick API request and save the response
autotoolkit api https://api.example.com/data --method get

Using it as a library

Every command is also a plain importable module, so you can call the underlying functions directly instead of shelling out:

from autotoolkit.duplicate_finder import find_duplicates
from autotoolkit.file_organizer import organize, DEFAULT_EXTENSION_MAP

duplicates = find_duplicates("/path/to/folder")
organize("/path/to/folder", DEFAULT_EXTENSION_MAP, dry_run=True)

Development

git clone https://github.com/Worof/Python-Automation-Toolkit.git
cd Python-Automation-Toolkit
pip install -e ".[dev,all]"
pytest --cov=autotoolkit

Security notes

• organize flags files with sensitive extensions (.key, .pem, .env, etc.) before moving them.
• api's --data argument is parsed as JSON, never evaluated as code.
• portscan is intended for hosts and networks you own or have permission to test.

Contributing

Issues and pull requests are welcome. Please run pytest before submitting.

License

MIT — see LICENSE.