vcfzap 1.0.0

A lightning-fast VCF contact extractor to CSV, TXT, JSON, or terminal preview

vcfzap

vcfzap is a high-performance, feature-rich command-line tool that extracts contact information from VCF (vCard) files and exports it into multiple formats: CSV, TXT, JSON, HTML, SQLite, or a color-coded terminal preview. Whether you're a developer, sysadmin, or power user, vcfzap makes contact extraction seamless and efficient.

---

✨ Key Features

• 🚀 Multi-format Export: Convert .vcf files to CSV, TXT, JSON, HTML, or SQLite database.
• 🧩 Field Selection: Choose exactly which fields to extract: name, phone, email, address, organization.
• 🔍 Dry Run Mode: Simulate output without creating any files — perfect for testing.
• 🌐 Encoding Detection: Automatically handles VCFs with different character encodings.
• 🔐 Safe Overwriting: Built-in prompts to prevent accidental file overwrite and respect for permissions.
• ⚡ Performance-focused: Fast parsing with progress display — handles large files effortlessly.
• ⌚ Timestamp Support: Automatically append timestamps to output filenames.
• 🧘 Automation-friendly: Flags like --no-color, --quiet, and --no-prompt are ideal for scripting and CI.
• 💽 Rich Terminal Preview: View a beautiful table-rendered contact list directly in the terminal.
• 🛠 Verbose Logging: Output logs to file and optionally enable debug mode for advanced insight.

---

⚙ Installation

📦 Install via PyPI

pip install vcfzap

🧬 Install from GitHub (latest)

git clone https://github.com/musaddiq/vcfzap.git
cd vcfzap
pip install .

---

🧪 Basic Usage

vcfzap <VCF_FILE> [OPTIONS]

✅ Examples

vcfzap contacts.vcf --preview --limit 5
vcfzap contacts.vcf --csv output.csv --timestamp
vcfzap contacts.vcf --json contacts.json --fields name,phone,email --pretty-json
vcfzap contacts.vcf --html contacts.html --fields email
vcfzap contacts.vcf --sqlite contacts.db --no-prompt
vcfzap --check-dependencies

---

⚙ Options & Arguments

📅 Input

• vcf_file (positional): Path to your .vcf file.

🎯 Output Formats (choose one)

• --csv <file>: Export to CSV file
• --txt <file>: Export to plain text file
• --json <file>: Export to JSON file
• --html <file>: Export to styled HTML table
• --sqlite <file>: Export to SQLite database
• --preview: Show contacts in a color-coded terminal table (no file output)

🎛 Behavior & Customization

• --fields name,phone,email: Comma-separated list of fields to extract
• --limit N: Limit number of contacts
• --timestamp: Add current timestamp to output filename
• --max-size N: Warn if file is larger than N MB
• --detect-encoding: Automatically detect file encoding
• --csv-delimiter ";": Set custom delimiter for CSV export
• --log-file <file>: Save detailed logs to specified file
• --no-color: Disable colored CLI output
• --quiet: Suppress non-essential messages
• --no-logs: Disable logging entirely
• --no-prompt: Disable all interactive prompts (force overwrite, large file warning)
• --pretty-json: Enable human-readable indented JSON
• --check-dependencies: Check for any missing Python dependencies
• -v, --version: Show version information

---

🌐 Field Reference

Field	Description
name	Full name (e.g., John Doe)
phone	Phone numbers with optional extensions
email	Email addresses
address	Full physical address
organization	Company or organization name

---

📦 Output Format Overview

Format	Description
CSV	Clean spreadsheet with optional delimiter
TXT	Readable text with labeled fields
JSON	Compact or pretty-printed structure
HTML	Styled responsive HTML table
SQLite	Structured database with dynamic schema
Preview	Terminal-based color table preview only

---

❗ Notes

• Only one output format can be specified per command.
• Use --dry-run to verify before exporting.
• Ideal for automation pipelines via --no-prompt, --quiet, and --log-file.

---

🧑‍💻 Advanced Usage

vcfzap mycontacts.vcf \
  --csv contacts.csv \
  --fields name,email,address \
  --timestamp \
  --detect-encoding \
  --log-file logs/vcfzap.log \
  --quiet

---

🛡 License

MIT License

👨‍💻 Author

Crafted with intent by Mallik Mohammad Musaddiq 📧 [e-mail] 🔗 GitHub Repo

---

🔍 Like vcfzap?

If this tool made your workflow easier, consider ⭐️ starring the repository or sharing it with others in need.