Forem: Vishwaraja Pathi (Vishwa)

Building a Secure Gmail CLI: From Development to Production 🚀

Vishwaraja Pathi (Vishwa) — Fri, 26 Sep 2025 10:46:05 +0000

How I built a comprehensive Gmail command-line interface with security-first design, Docker containerization, and CI/CD automation.

🎯 The Problem

As developers, we live in our terminals. We manage code, deploy applications, and debug issues all from the command line. But when it comes to email management, we're forced to switch to web browsers or desktop applications, breaking our workflow.

What if we could manage Gmail directly from the terminal? What if we could read emails, send messages, manage drafts, and configure settings without leaving our development environment?

💡 The Solution: Gmail CLI

I built Gmail CLI - a comprehensive command-line interface for Gmail that brings the full power of Gmail's API to your terminal. It's not just another email client; it's a developer-focused tool designed to integrate seamlessly into your workflow.

✨ Key Features

📧 Core Email Operations

List emails with rich formatting and filtering
Read emails with full HTML/text support
Send emails with attachments and rich formatting
Search emails with Gmail's powerful search syntax
Mark as read/unread for efficient email management
Delete emails and threads

�� Advanced Features

Draft Management - Create, read, update, and send drafts
Thread Management - View and manage conversation threads
Label Management - Create custom labels and organize emails
Settings Management - Configure filters, forwarding, and vacation responders
Attachment Support - Download and manage email attachments

🔐 Security-First Design

OAuth2 Authentication - No password storage, secure token-based auth
Secure Credential Storage - Credentials stored in user home directory
Environment Variable Configuration - Flexible credential path management
Comprehensive .gitignore - Prevents accidental credential commits

��️ Technical Implementation

Architecture

The CLI is built with Python and leverages several key technologies:

Google Gmail API - Full access to Gmail's capabilities
OAuth2 Authentication - Secure, token-based authentication
Click Framework - Beautiful command-line interface
Rich Library - Rich text formatting and progress bars
Docker - Containerized deployment for consistency

Key Components

# Core Gmail client with comprehensive API coverage
class GmailClient:
    def __init__(self, credentials_path: str):
        self.service = self._build_service(credentials_path)

    # Email operations
    def list_messages(self, query: str = None, max_results: int = 10)
    def get_message(self, message_id: str)
    def send_message(self, to: str, subject: str, body: str)

    # Draft management
    def create_draft(self, to: str, subject: str, body: str)
    def list_drafts(self, max_results: int = 10)

    # And much more...

🔒 Security: The Most Important Feature

The Problem with Credentials

One of the biggest challenges in building CLI tools is handling credentials securely. Too many projects accidentally commit sensitive files to version control, exposing API keys and tokens.

Our Security Solution

1. Secure Credential Storage

# Credentials stored in secure user directory
~/.gmail-cli/credentials.json  # Google API credentials
~/.gmail-cli/token.json        # OAuth2 tokens

2. Environment Variable Configuration

class GmailAuthenticator:
    def __init__(self, credentials_file: Optional[str] = None, token_file: Optional[str] = None):
        # Use environment variables or secure defaults
        self.credentials_file = credentials_file or os.getenv(
            'GMAIL_CREDENTIALS_PATH', 
            os.path.expanduser('~/.gmail-cli/credentials.json')
        )
        self.token_file = token_file or os.getenv(
            'GMAIL_TOKEN_PATH', 
            os.path.expanduser('~/.gmail-cli/token.json')
        )

3. Comprehensive .gitignore

# Google API credentials and tokens
token.json
credentials.json
*.json
!package.json
!tsconfig.json
!*.config.json

# Additional security patterns
*.pem
*.key
*.p12
*.pfx
secrets/
.secrets/

4. Automated Security Setup

# Secure setup script that:
# - Creates secure directories
# - Moves credentials from project directory
# - Sets proper file permissions
# - Configures environment variables
./secure-setup.sh

🐳 Docker: Simplified and Secure

Why We Removed Docker Compose

Initially, I used Docker Compose for the project, but I realized it was overkill for a single image. Docker Compose is great for multi-service applications, but for a single CLI tool, it adds unnecessary complexity.

Simplified Docker Setup

Before (Docker Compose):

version: '3.8'
services:
  gmail-cli:
    build: .
    volumes:
      - ./credentials.json:/app/credentials.json:ro
      - ./token.json:/app/token.json
    # ... complex configuration

After (Simple Docker):

# Simple, secure Docker commands
docker run -it --rm \
  -v $(pwd)/data:/app/data \
  -v ~/.gmail-cli/credentials.json:/app/credentials.json:ro \
  -v ~/.gmail-cli/token.json:/app/token.json \
  -e GMAIL_CREDENTIALS_PATH="/app/credentials.json" \
  -e GMAIL_TOKEN_PATH="/app/token.json" \
  vishwa86/gmail-cli:latest list

Docker Runner Script

#!/bin/bash
# Simplified script that handles:
# - Credential security checks
# - Automatic credential migration
# - Proper volume mounting
# - Environment variable setup

./docker-run.sh list          # List emails
./docker-run.sh send --to user@example.com --subject "Hello" --body "Test"
./docker-run.sh shell         # Interactive shell

�� CI/CD Pipeline

Automated Workflows

The project includes a comprehensive CI/CD pipeline using GitHub Actions:

CI Pipeline - Runs tests on Python 3.8-3.11, linting, and security scans
Docker Build - Multi-architecture builds on every push
Automated Deployment - Pushes to Docker Hub on main branch merges
Version Management - Automatic tagging for releases

Workflow Features

# Multi-architecture builds
platforms: linux/amd64,linux/arm64

# Automated testing
- name: Test CLI help command
  run: gmail --help

# Security scanning
- name: Run Trivy vulnerability scanner
  uses: aquasecurity/trivy-action@master

📊 Usage Examples

Daily Email Management

# Check your inbox
gmail list

# Read a specific email
gmail read <message-id>

# Search for emails from a specific sender
gmail search "from:boss@company.com"

# Mark important emails as read
gmail mark read <message-id>

Draft Management

# Create a draft for later
gmail drafts create \
  --to "client@example.com" \
  --subject "Proposal Review" \
  --body "Please find attached..."

# List all drafts
gmail drafts list

# Send a draft when ready
gmail drafts send <draft-id>

Advanced Operations

# Download attachments
gmail download <message-id> <attachment-id>

# Create custom labels
gmail label create "Important Projects" --color "red"

# Set up vacation responder
gmail settings vacation \
  --enable \
  --subject "Out of Office" \
  --message "I'm currently away..."

🎨 User Experience

Rich Terminal Output

The CLI uses the Rich library to provide:

Colorized output for better readability
Progress bars for long operations
Tables for structured data display
Syntax highlighting for email content

Comprehensive Help System

# Get detailed help with examples
gmail help-detailed

# Command-specific help
gmail send --help
gmail drafts --help

🔮 Lessons Learned

1. Security First

Always design with security in mind from the start
Use environment variables for configuration
Implement comprehensive .gitignore rules
Create automated security setup scripts

2. Simplicity Over Complexity

Docker Compose isn't always necessary
Simple Docker commands can be more maintainable
Focus on the core functionality first

3. Developer Experience

Rich terminal output improves usability
Comprehensive help systems reduce learning curve
Consistent command structure across all operations

4. Automation is Key

CI/CD pipelines catch issues early
Automated security scanning prevents vulnerabilities
Multi-architecture builds ensure compatibility

�� Getting Started

Prerequisites

Google Cloud Project with Gmail API enabled
OAuth2 Credentials downloaded from Google Cloud Console
Docker (optional but recommended)

Installation

# Using Docker (Recommended)
git clone https://github.com/vishwaraja/gmail-cli.git
cd gmail-cli
./docker-setup.sh
./secure-setup.sh
./docker-run.sh auth

First Run

# Authenticate with Gmail
gmail auth

# Start using the CLI
gmail list

�� Resources

GitHub Repository: github.com/vishwaraja/gmail-cli
Docker Hub: hub.docker.com/r/vishwa86/gmail-cli
Documentation: Comprehensive README with examples
Security Guide: Detailed security best practices

🤝 Contributing

The project is open source and welcomes contributions:

Bug Reports: Help improve stability
Feature Requests: Suggest new functionality
Code Contributions: Submit pull requests
Documentation: Improve guides and examples

💭 Conclusion

Gmail CLI represents more than just a command-line email client. It's a testament to the power of developer-focused tools that integrate seamlessly into existing workflows. By bringing Gmail to the terminal, we're not just changing how we manage emails—we're reimagining the developer experience.

The journey from initial development to production-ready tool taught me valuable lessons about security, simplicity, and automation. The most important takeaway: security should be designed in from the start, not bolted on later.

Whether you're a terminal enthusiast, a DevOps engineer, or simply someone who values efficiency, Gmail CLI offers a new way to interact with one of the most important communication tools in our digital lives.

Ready to transform your email workflow? Give Gmail CLI a try and experience the power of terminal-based email management.

What's your experience with command-line email tools? Have you tried Gmail CLI? Share your thoughts and experiences in the comments below!

Building a Comprehensive Reddit CLI Tool: From Basic Posting to Full Reddit Management with 33+ Commands

Vishwaraja Pathi (Vishwa) — Fri, 26 Sep 2025 08:52:43 +0000

Building a Comprehensive Reddit CLI Tool: From Basic Posting to Full Reddit Management

🚀 A complete journey from a simple Reddit posting tool to a professional-grade CLI with 33+ commands, Docker support, and comprehensive Reddit API integration.

The Problem

As a developer and Reddit enthusiast, I found myself needing to:

Post content across multiple subreddits efficiently
Monitor discussions and engage with communities
Research topics and find relevant subreddits
Manage my Reddit presence programmatically

Existing tools were either too complex, limited in functionality, or required extensive setup. I needed something that was both powerful and easy to use.

The Solution: Reddit CLI Tool

I built a comprehensive command-line interface that provides 33+ commands covering every aspect of Reddit interaction. Here's what makes it special:

�� Key Features

📝 Complete Content Management: Post, edit, delete, and manage Reddit content
💬 Advanced Commenting: Comment, reply, and engage with communities
🔍 Powerful Search: Search posts, comments, and subreddits across Reddit
👥 User Management: View profiles, follow users, and manage relationships
�� Content Discovery: Find trending subreddits and hot posts
💾 Content Organization: Save, unsave, and organize your Reddit content
�� Messaging System: Send and receive private messages
🗳️ Voting System: Upvote and downvote posts and comments
🏷️ Flair Support: Use subreddit flairs for better categorization
🐳 Docker Ready: Easy deployment with Docker containers

🚀 Quick Start

# Clone and setup
git clone https://github.com/vishwaraja/reddit-cli.git
cd reddit-cli
./setup.sh

# Start using immediately
./run.sh post askreddit "What's your favorite programming language?" --content "I'm curious about what developers prefer and why."

Technical Implementation

Architecture

The tool is built with:

Python 3.11+ with PRAW (Python Reddit API Wrapper)
Docker for easy deployment and consistency
Comprehensive error handling with exponential backoff
Rate limiting to comply with Reddit's API limits
Beautiful terminal output with emojis and clear formatting

Command Categories

📝 Content Management (6 commands)

./run.sh post askreddit "Title" --content "Content"
./run.sh comment "post_url" "comment_text"
./run.sh edit-post "post_url" "new_content"
./run.sh delete "post_url"

🔍 Discovery & Search (6 commands)

./run.sh search-subreddits "machine learning" --limit 10
./run.sh search-posts "Python tutorial" --subreddit "learnpython"
./run.sh hot programming --limit 10
./run.sh trending --limit 10

👥 User Management (4 commands)

./run.sh user-profile "spez"
./run.sh user-posts "username" --limit 10
./run.sh follow "username"
./run.sh friends

🗳️ Voting & Engagement (2 commands)

./run.sh upvote "post_url"
./run.sh downvote "post_url"

📬 Messaging (2 commands)

./run.sh message "username" "Subject" "Message body"
./run.sh inbox --limit 10

🏷️ Subreddit Management (6 commands)

./run.sh flairs askreddit
./run.sh subreddit-info "MachineLearning"
./run.sh subscribe "MachineLearning"
./run.sh moderators "MachineLearning"

�� Monitoring (2 commands)

./run.sh responses "post_url" --limit 20
./run.sh monitor "post_url" --interval 60

Beautiful Help System

The tool features a comprehensive help system with emoji-rich commands and detailed examples:

./run.sh --help

Shows all 33+ commands with clear descriptions and usage examples.

Real-World Use Cases

Content Creators

Automated Posting: Schedule and manage content across multiple subreddits
Community Engagement: Monitor responses and engage with your audience
Content Research: Find trending topics and popular discussions

Developers

Project Promotion: Share your open-source projects with relevant communities
Technical Discussions: Participate in programming and tech subreddits
Learning Resources: Find and share educational content

Researchers

Data Collection: Gather insights from Reddit discussions
Trend Analysis: Monitor trending topics and community sentiment
Academic Research: Study online communities and social behavior

Business Users

Brand Management: Monitor mentions and engage with customers
Market Research: Understand customer needs and preferences
Community Building: Build and nurture online communities

Technical Challenges & Solutions

Rate Limiting

Reddit has strict API rate limits. I implemented:

Exponential backoff for failed requests
Automatic retry logic with configurable delays
User-friendly error messages explaining rate limits

Error Handling

Comprehensive error handling for:

Authentication issues (401 errors)
Permission problems (403 errors)
Network timeouts and connection issues
Invalid input validation

Docker Integration

Made the tool Docker-ready for:

Easy setup without Python environment conflicts
Consistent deployment across different systems
Isolated execution environment

Code Quality & Best Practices

Professional Features

Type hints throughout the codebase
Comprehensive docstrings for all functions
Modular architecture with clear separation of concerns
Consistent error handling patterns
User-friendly output with emojis and clear formatting

Open Source Ready

MIT License for maximum compatibility
Comprehensive README with examples and documentation
Docker support for easy deployment
GitHub repository with proper structure

Results & Impact

What We Achieved

33+ commands covering all major Reddit APIs
Professional-grade error handling and rate limiting
Docker containerization for easy deployment
Comprehensive documentation and help system
Open source with MIT license

User Experience

Beautiful terminal output with emojis and clear formatting
Intuitive command structure that's easy to remember
Comprehensive help system with examples
Fast execution with proper rate limiting

Future Enhancements

While the tool is already feature-complete, potential future enhancements include:

Cross-posting functionality
Advanced moderation tools
Analytics and insights features
Scheduling capabilities
Web interface for non-technical users

Getting Started

Prerequisites

Docker (recommended) or Python 3.11+
Reddit API credentials

Quick Setup

# Clone the repository
git clone https://github.com/vishwaraja/reddit-cli.git
cd reddit-cli

# Run setup script
./setup.sh

# Configure your Reddit API credentials
cp reddit_config.json.example reddit_config.json
# Edit reddit_config.json with your credentials

# Start using!
./run.sh --help

Reddit API Setup

Go to Reddit App Preferences
Click "Create App" or "Create Another App"
Fill in the form:
- Name: Any name (e.g., "My Reddit CLI")
- App type: Select "script"
- Redirect URI: http://localhost:8080
Note down your Client ID and Client Secret

Conclusion

Building this Reddit CLI tool was an incredible journey that taught me:

API Integration: How to work with complex APIs like Reddit's
Error Handling: The importance of robust error handling and user feedback
User Experience: How small details like emojis and clear formatting make a big difference
Docker: The power of containerization for easy deployment
Open Source: The value of building tools that others can use and contribute to

The tool is now production-ready with 33+ commands, comprehensive error handling, and professional-grade features. It's open source, well-documented, and ready for the community to use and contribute to.

Key Takeaways

Start simple, iterate fast: We began with basic posting and gradually added features
User experience matters: Beautiful output and clear help make tools more usable
Error handling is crucial: Robust error handling prevents user frustration
Documentation is key: Good documentation makes tools accessible to everyone
Open source benefits everyone: Sharing tools helps the entire community

Resources

GitHub Repository: https://github.com/vishwaraja/reddit-cli
Reddit API Documentation: https://praw.readthedocs.io/
Docker Documentation: https://docs.docker.com/

What do you think? Have you built similar CLI tools? What challenges did you face? Let me know in the comments!

python #reddit #cli #automation #praw #docker #opensource #api #commandline

Building a PDF Parser for HDFC Bank Statements: From 165 Pages to CSV in Minutes

Vishwaraja Pathi (Vishwa) — Thu, 25 Sep 2025 05:06:36 +0000

Building a PDF Parser for HDFC Bank Statements: From 165 Pages to CSV in Minutes

🚀 GitHub Repository | ⭐ Star it if you find it useful!

The Problem That Started It All

Picture this: You're an auditor, accountant, or financial analyst staring at a 165-page HDFC Bank statement with 3,602 transactions that need to be converted to CSV format. The manual process would take days, and the risk of errors is enormous.

That's exactly the challenge I faced recently, and it led me to build an open-source solution that I'm excited to share with the community.

The Solution: HDFC PDF to CSV Converter

I created a Python tool that automatically extracts all transactions from HDFC Bank PDF statements and converts them to CSV format with intelligent categorization. Here's what it accomplishes:

✅ 100% extraction rate from 165-page PDFs
✅ 3,602 transactions processed automatically
✅ 22 automatic categories (UPI, Foreign Exchange, Salary, etc.)
✅ Multi-line narration support for complex transactions
✅ Multiple output formats (CSV, Excel, Markdown)
✅ Command-line interface for easy automation

Quick Start

# Clone the repository
git clone https://github.com/vishwaraja/hdfc-pdf-converter.git
cd hdfc-pdf-converter

# Install dependencies
pip install -r requirements.txt

# Convert your first PDF (creates ./results/ directory automatically)
python src/hdfc_converter.py your_statement.pdf

Technical Deep Dive

The Tech Stack

# Core dependencies
camelot-py[cv]  # PDF table extraction
pandas          # Data manipulation
PyPDF2          # PDF processing
pdfplumber      # Text extraction

The Challenge: Multi-line Narrations

One of the biggest challenges was handling transactions where the narration spans multiple lines. Here's how I solved it:

def _parse_transaction_row(self, row, page_num):
    """Parse a single transaction row with multi-line support."""
    # Handle multi-line narrations
    narration_parts = []

    # Everything between date and amounts is narration
    narration_start = 1
    narration_end = len(row) - 5

    for i in range(narration_start, narration_end):
        part = str(row.iloc[i]).strip()
        if part and part != 'nan':
            narration_parts.append(part)

    narration = ' '.join(narration_parts)
    return narration

Intelligent Categorization

The tool automatically categorizes transactions into 22 meaningful categories:

def categorize_transaction(narration):
    narration_lower = str(narration).lower()

    if any(word in narration_lower for word in ['salary', 'payroll', 'betterplace']):
        return 'Salary & Employment'
    elif any(word in narration_lower for word in ['foreign', 'usd', 'eur', 'gbp']):
        return 'Foreign Exchange'
    elif any(word in narration_lower for word in ['upi']):
        return 'UPI Payments'
    # ... and 19 more categories

Real Results

Here's what the tool achieved with my 165-page statement:

Metric	Result
Total Transactions	3,602
Pages Processed	165/165 (100%)
Extraction Time	~2 minutes
Categories Identified	22
Data Quality	100% valid dates

Sample Output

Date,Narration,Category,Withdrawal_Amount,Deposit_Amount
15/07/2020,UPI payment to merchant,UPI Payments,150.00,0.00
16/07/2020,Salary credit from company,Salary & Employment,0.00,25000.00
17/07/2020,Foreign remittance from USA,Foreign Exchange,0.00,50000.00

Usage Examples

Command Line Interface

# Basic usage (creates ./results/ directory automatically)
python src/hdfc_converter.py statement.pdf

# Custom output directory
python src/hdfc_converter.py statement.pdf --output-dir ./my_results

# Verbose logging for debugging
python src/hdfc_converter.py statement.pdf --verbose

# Convert PDF from different directory
python src/hdfc_converter.py /path/to/statements/hdfc_2024.pdf

Programmatic API

from src.hdfc_converter import HDFCConverter

# Initialize converter
converter = HDFCConverter('statement.pdf', output_dir='./results')

# Convert PDF to CSV
success = converter.convert()

if success:
    print("✅ Conversion completed successfully!")

The Impact

This tool has already saved me hours of manual work and eliminated the risk of transcription errors. But more importantly, it's now available as an open-source solution for the entire community.

Key Benefits for Users:

Auditors: Quick conversion of bank statements for analysis
Accountants: Automated data entry from PDF statements
Fintech Developers: Foundation for building banking tools
Data Analysts: Clean CSV data for financial analysis

Open Source and Community

I've made this tool completely open source with:

📚 Comprehensive documentation
🧪 Unit tests and examples
🤝 Contribution guidelines
📋 Issue templates and PR templates
🔄 CI/CD pipeline

🔗 Repository: https://github.com/vishwaraja/hdfc-pdf-converter

What's Next?

I'm excited to see how the community will use and improve this tool. Some potential enhancements:

Support for other bank PDF formats
GUI interface for non-technical users
Cloud processing capabilities
Advanced filtering and search features

Lessons Learned

Building this tool taught me several valuable lessons:

PDF parsing is complex - Different banks use different formats
Multi-line data is tricky - Requires careful parsing logic
Categorization needs intelligence - Simple regex isn't enough
Documentation is crucial - Makes tools accessible to others
Open source is powerful - Community feedback improves everything

Get Started

Ready to try it out? Here's how to get started:

# Clone the repository
git clone https://github.com/vishwaraja/hdfc-pdf-converter.git
cd hdfc-pdf-converter

# Install dependencies
pip install -r requirements.txt

# Convert your first PDF
python src/hdfc_converter.py your_statement.pdf

Conclusion

What started as a personal problem-solving exercise became a tool that could benefit the entire developer and financial community. This is the power of open source - turning individual solutions into community resources.

I'd love to hear your thoughts, suggestions, and use cases. Have you faced similar challenges with PDF processing? What other banking tools would be useful to the community?

Connect with me:

Have questions about PDF parsing or want to contribute to the project? Leave a comment below - I'd love to discuss!

Forem: Vishwaraja Pathi (Vishwa)

Building a Secure Gmail CLI: From Development to Production 🚀

🎯 The Problem

💡 The Solution: Gmail CLI

✨ Key Features

📧 Core Email Operations

�� Advanced Features

🔐 Security-First Design

��️ Technical Implementation

Architecture

Key Components

🔒 Security: The Most Important Feature

The Problem with Credentials

Our Security Solution

1. Secure Credential Storage

2. Environment Variable Configuration

3. Comprehensive .gitignore

4. Automated Security Setup

🐳 Docker: Simplified and Secure

Why We Removed Docker Compose

Simplified Docker Setup

Before (Docker Compose):

After (Simple Docker):

Docker Runner Script

�� CI/CD Pipeline

Automated Workflows

Workflow Features

📊 Usage Examples

Daily Email Management

Draft Management

Advanced Operations

🎨 User Experience

Rich Terminal Output

Comprehensive Help System

🔮 Lessons Learned

1. Security First

2. Simplicity Over Complexity

3. Developer Experience

4. Automation is Key

�� Getting Started

Prerequisites

Installation

First Run

�� Resources

🤝 Contributing

💭 Conclusion

Tags

Building a Comprehensive Reddit CLI Tool: From Basic Posting to Full Reddit Management with 33+ Commands

Building a Comprehensive Reddit CLI Tool: From Basic Posting to Full Reddit Management

The Problem

The Solution: Reddit CLI Tool

�� Key Features

🚀 Quick Start

Technical Implementation

Architecture

Command Categories

📝 Content Management (6 commands)

🔍 Discovery & Search (6 commands)

👥 User Management (4 commands)

🗳️ Voting & Engagement (2 commands)

📬 Messaging (2 commands)

🏷️ Subreddit Management (6 commands)

�� Monitoring (2 commands)

Beautiful Help System

Real-World Use Cases

Content Creators

Developers

Researchers

Business Users

Technical Challenges & Solutions

Rate Limiting

Error Handling

Docker Integration

Code Quality & Best Practices

Professional Features

Open Source Ready

Results & Impact

What We Achieved

User Experience

Future Enhancements