Gmail signature deployment CLI for Google Workspace
Project description
Hancock
Gmail signature deployment CLI for Google Workspace
Deploy signatures to your entire Google Workspace from the terminal. Simple, fast, and secure.
pip install hancock-cli
hancock init
hancock deploy signatures/
✨ Features
- 🚀 Simple Setup - One command to configure, works with Google service accounts
- 🎯 Smart Matching - Automatically matches signature files to users by name or email
- 📊 Beautiful UI - Colored terminal output with progress bars and clear status
- ✅ Validation - Checks file sizes, formats, and matching before deployment
- 🔒 Secure - Your credentials stay on your machine, no data sent elsewhere
- ⚡ Fast - Deploy to entire organization in minutes
- 💻 Terminal Native - Works great standalone or with Claude Code
🚀 Quick Start
Install
Choose your operating system:
macOS:
python3 -m pip install hancock-cli
Windows:
pip install hancock-cli
If this doesn't work, install Python first and check "Add Python to PATH"
Linux:
pip3 install hancock-cli
If pip3 isn't found, run: sudo apt install python3-pip (Ubuntu/Debian) or sudo yum install python3-pip (CentOS/RHEL)
Setup (5-15 minutes, one time only)
hancock init
This walks you through:
- Locating your Google Cloud service account JSON key
- Entering your Google Workspace admin email
- Validating credentials
Deploy
Create a folder with HTML signature files named to match your users:
signatures/
├── john.smith.html
├── jane-doe.html
└── bob.jones.html
Then deploy:
hancock deploy signatures/
📖 Commands
hancock init
Interactive setup - configure credentials and validate access.
hancock deploy <folder>
Deploy signatures from a folder to matched users.
Options:
--dry-run- Show what would be deployed without actually deploying
Example:
hancock deploy signatures/
hancock deploy ~/my-signatures/ --dry-run
hancock preview <email>
Preview the current signature for a user.
Example:
hancock preview john@company.com
hancock validate <folder>
Validate signature files without deploying.
Example:
hancock validate signatures/
hancock config
Show current configuration and status.
🎯 Creating Signatures
File Naming
Name your HTML files to match users:
john.smith.html→john.smith@company.comjane-doe.html→jane.doe@company.combobsmith.html→bob.smith@company.com
Hancock handles:
- Dots, dashes, underscores
- Different name orders
- Case insensitive matching
- "sig" or "signature" suffixes
Basic Template
<!DOCTYPE html>
<html>
<body>
<table style="font-family: Arial, sans-serif; font-size: 12px;">
<tr>
<td>
<p style="margin: 0; font-weight: bold;">John Smith</p>
<p style="margin: 5px 0; color: #666;">Software Engineer</p>
<p style="margin: 0;">
<a href="mailto:john@company.com">john@company.com</a>
</p>
</td>
</tr>
</table>
</body>
</html>
Images (No External Hosting)
Use base64 encoding to embed images directly:
# Convert image to base64
base64 -i photo.jpg | tr -d '\n'
Then in your HTML:
<img src="data:image/jpeg;base64,YOUR_BASE64_HERE"
style="width: 80px; height: 80px;" />
Size Limit
Gmail signatures must be under 10KB. Hancock validates this automatically.
Tips to reduce size:
- Optimize images before base64 encoding
- Use JPEG instead of PNG for photos
- Keep HTML simple and minimal
🔐 Service Account Setup
Hancock uses a Google Cloud service account with domain-wide delegation. This is the same approach used by many enterprise tools.
First-Time Setup (15 minutes)
-
Go to Google Cloud Console
-
Create a new project (or select existing)
-
Enable APIs:
- Admin SDK API
- Gmail API
-
Create Service Account:
- Go to: IAM & Admin → Service Accounts
- Create service account
- Download JSON key
-
Enable Domain-Wide Delegation:
- Edit service account
- Enable domain-wide delegation
- Note the Client ID
-
Authorize in Google Workspace:
- Go to Google Workspace Admin Console
- Security → API Controls → Domain-wide Delegation
- Add new with Client ID and scopes:
https://www.googleapis.com/auth/admin.directory.user.readonly https://www.googleapis.com/auth/gmail.settings.basic
-
Run Hancock init:
hancock init
Security
✅ Hancock is secure by design:
- Your credentials stay on your machine
- No data sent to third parties
- Standard Google OAuth 2.0
- Open source - audit the code
✅ Best practices:
- Keep your service account JSON secure
- Don't commit credentials to git
- Review Google Workspace audit logs
💡 Use Cases
- Company rebrand - Update all signatures at once
- New hires - Standardize onboarding signatures
- Legal compliance - Ensure signatures meet requirements
- Marketing campaigns - Add promotional content
- Department changes - Update titles and departments
✨ Using with Claude Code
Hancock works great in Claude Code!
Claude can help you:
- Walk through the Google Cloud setup
- Find your service account JSON file
- Troubleshoot configuration issues
- Create signature HTML files
- Validate your setup
Just run hancock init in the Claude Code terminal and Claude will guide you through!
🛠 Troubleshooting
"Hancock is not configured yet"
→ Run hancock init to set up credentials
"Authentication failed"
→ Verify domain-wide delegation is enabled → Check OAuth scopes in Workspace Admin Console → Confirm admin email is correct
"No signatures matched to users"
→ Check filename format (use email prefix or full name) → Verify users exist in Google Workspace → Try different separator styles (dots vs dashes)
"File size exceeds limit"
→ Signatures must be under 10KB → Reduce image dimensions → Optimize images before base64 encoding
📦 Installation
From PyPI (recommended)
macOS / Linux:
python3 -m pip install hancock-cli
Windows:
pip install hancock-cli
From source
git clone https://github.com/HappyPayton/hancock-cli.git
cd hancock-cli
python3 -m pip install -e .
Requirements
- Python 3.7 or higher - Download Python if not installed
- Google Workspace admin access
- Google Cloud service account with domain-wide delegation
Troubleshooting Installation
"pip: command not found" or "pip3: command not found"
- Use
python3 -m pip install hancock-cliinstead - On Mac: Python 3 is pre-installed, use
python3andpip3 - On Windows: Install Python from python.org and check "Add to PATH"
- On Linux: Run
sudo apt install python3-pip(Ubuntu/Debian)
🔄 Uninstall
pip uninstall hancock-cli
Your configuration file (~/.hancock/config.yaml) will remain. Delete it manually if desired.
📝 License
MIT License - Free to use and distribute
🌟 Why Hancock?
Simple
- One install command
- Interactive setup
- Terminal-native workflow
Powerful
- Deploy to entire organization
- Smart filename matching
- Real-time progress tracking
Secure
- Standard Google OAuth
- Credentials stay local
- Open source
🚀 Get Started
pip install hancock-cli
hancock init
Questions? File an issue on GitHub
Made with ❤️ for Google Workspace administrators
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file hancock_cli-1.0.3.tar.gz.
File metadata
- Download URL: hancock_cli-1.0.3.tar.gz
- Upload date:
- Size: 23.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.9.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c20bb8ef694152570d3a87cfa12632291cf0d5348df6b94eea0c22248f79c756
|
|
| MD5 |
95e616c5f155daa2bac4955b21789400
|
|
| BLAKE2b-256 |
e4ee81e4328fe4b51986c6a69b505a8e93b384c7e3268320d3b4d41b834806b0
|
File details
Details for the file hancock_cli-1.0.3-py3-none-any.whl.
File metadata
- Download URL: hancock_cli-1.0.3-py3-none-any.whl
- Upload date:
- Size: 23.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.9.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b0d84a3b304286b65c27af14f0a8e672ef6610d88804d2709a890b683d280df6
|
|
| MD5 |
ef4c63946ddf0b37793ef83bffe39c9a
|
|
| BLAKE2b-256 |
7ca4bf302535ba9330b157de878221711bf93ce68403c8cbd98e899de08a3ca9
|
