A comprehensive command-line interface for managing Forward Email accounts and resources through their public REST API. This CLI provides a powerful interface to manage your domains, aliases, and email operations programmatically.
Status: Production Ready ✅ | LOC: 17,151 | Tests: 100+ passing | Platform: Linux/macOS/Windows
- Complete API Coverage: Full coverage for domains, aliases, and email; account/logs planned
- Multi-Profile Support: Development, staging, and production environments
- Security First: OS keyring integration with secure credential storage
- Developer Experience: Comprehensive help system and interactive operations
- Multiple Output Formats: Table, JSON, YAML, CSV, plain with filtering and sorting
- Cross-Platform: Native support for Linux, macOS, and Windows
- First-Mover Advantage: Forward Email's first official CLI tool
# Build from source
git clone https://github.com/ginsys/forward-email.git
cd forward-email
go build -o bin/forward-email ./cmd/forward-email
# Check version (optional)
./bin/forward-email version --verbose
# Set up authentication
./bin/forward-email auth login
# List your domains
./bin/forward-email domain list
# Create an alias
./bin/forward-email alias create info@example.com --domain example.com --recipients team@company.com# First-time setup
forward-email init # Interactive setup wizard
# Version info
forward-email version --verbose # Detailed version info
# Authentication & Profiles
forward-email auth login # Interactive API key setup
forward-email profile create prod # Create production profile
forward-email profile switch prod # Switch to production profile
# Domain Management
forward-email domain list # List all domains
forward-email domain create example.com # Add new domain
forward-email domain verify example.com # DNS/SMTP verification
# Alias Operations
forward-email alias list --domain example.com
forward-email alias create info@example.com --domain example.com --recipients team@company.com
forward-email alias sync merge domain1.com domain2.com # Sync aliases between domains
# Email Operations
forward-email email send # Interactive email composition
forward-email email list # View sent email history- Authentication: Multi-source credential management (env → keyring → config)
- Profiles: Multi-environment configuration management
- Domains: Complete CRUD operations with DNS verification
- Aliases: Full lifecycle management with all settings
- Email: Interactive and programmatic sending with attachments
- Output: Multiple formats with filtering and sorting
- Init Wizard: Interactive first-time setup
- Shell Completion: bash, zsh, fish, PowerShell
- Testing: 100+ test cases across all packages
- Enhanced test coverage for email services
- Bulk operations and CSV import/export
- Automated CI/CD pipeline
Current Status: Pre-release development (v0.x.x)
This project is under active development towards v1.0.0. Until then:
⚠️ Breaking changes may occur in any release⚠️ No backwards compatibility guaranteed⚠️ API interfaces may change without deprecation notices- ✅ After v1.0.0: Semantic versioning with proper deprecation cycles
The CLI targets Forward Email API v1. While we strive for stability, please pin to specific versions in production use.
See docs/RELEASING.md for details on versioning policy, semantic versioning, and release workflow.
# Install dependencies
go mod download
# Run tests
go test ./...
# Build binary
make build
# Run linter
make lint- Documentation Index - Central entry point for all docs
- Releasing - Versioning policy and release workflow
- Command Reference - Complete command documentation
- Configuration Guide - Profiles, environments, and settings
- Troubleshooting - Common issues and solutions
- Contributing Guide - How to contribute to the project
- Architecture Overview - System design and structure
- API Integration - Forward Email API details
- API Reference - Complete API endpoint mapping
- Testing Strategy - Testing approach and standards
- Makefile Guide - Build and development commands
- Domain Alias Sync Specification - Bulk alias synchronization feature
We welcome contributions! Please see our Contributing Guide for details.
- Framework: Cobra CLI with Viper configuration
- Authentication: HTTP Basic with Forward Email API
- Storage: OS keyring integration for secure credentials
- Testing: Comprehensive mock-based testing strategy
- Output: Consistent formatting across all operations
This project is licensed under the MIT License - see the LICENSE file for details.
- Forward Email for providing the comprehensive API
- Cobra for the excellent CLI framework
- The Go community for outstanding tooling and libraries
Built with ❤️ for the Forward Email community | Last Updated: 2026-01-18