CLI Overview

The mailiam CLI is your primary interface for managing email infrastructure, forms, and domains. Built for developers who prefer configuration-as-code workflows.

Installation

npm (Recommended)

npm install -g mailiam

Verify Installation

mailiam --version
mailiam --help

Quick Start

1. Instant Form (Zero Config)

mailiam form
# Returns: https://api.mailiam.dev/f/abc123def

2. Domain-Based Project

mailiam init mysite.com
cd mysite.com
mailiam push

Core Concepts

Config-First Approach

mailiam treats email infrastructure like code:

• mailiam.config.yaml - Single source of truth
• Version control - Track changes with Git
• Environments - Dev, staging, production configs
• Deployment - mailiam push like git push

The CLI Philosophy

# Initialize like git
mailiam init mysite.com

# Configure like infrastructure
vim mailiam.config.yaml

# Deploy like code
mailiam push

# Monitor like production
mailiam status

Command Categories

Core Commands

• mailiam init - Initialize new project
• mailiam push - Deploy configuration
• mailiam pull - Sync remote changes
• mailiam status - Check deployment status

Instant Forms

• mailiam form - Create instant form endpoint
• mailiam forms - Manage project forms

Collections

• mailiam collections - Manage form collections
• Collection-based organization for multiple forms

Domains

• mailiam domains - Manage custom domains
• DNS configuration and verification

Projects

• mailiam projects - Manage domain projects
• Templates, branding, and organization

Configuration File

Basic Structure

mailiam.config.yaml

domains:
  mysite.com:
    forwarding:
      "*@mysite.com": "me@gmail.com"
    forms:
      contact:
        template: "professional"
        replies: true
    projects:
      main:
        templates: "./templates/"
        branding: "./brand/"

collections:
  company:
    name: "Company Forms"
    settings:
      rateLimit: 100
      spamProtection: true
    forms:
      contact:
        name: "Contact Form"
        email: "contact@company.com"
      feedback:
        name: "Feedback Form"
        email: "feedback@company.com"

Environment-Specific Configs

# Different environments
mailiam.config.yaml         # Default/production
mailiam.config.dev.yaml     # Development
mailiam.config.staging.yaml # Staging

# Deploy to specific environment
mailiam push --env dev
mailiam push --env staging
mailiam push --env production  # default

Authentication

API Key Setup

# Login interactively
mailiam login

# Set API key manually
mailiam config set apiKey sk-abc123def456

# Use environment variable
export MAILIAM_API_KEY=sk-abc123def456

Key Management

# List API keys
mailiam keys list

# Create new key
mailiam keys create "Production Deploy" --permissions deploy,read

# Rotate key
mailiam keys rotate sk-abc123def456

# Revoke key
mailiam keys revoke sk-abc123def456

Global Options

Common Flags

# Verbose output
mailiam push --verbose

# Quiet mode (minimal output)
mailiam push --quiet

# Dry run (preview changes)
mailiam push --dry-run

# Specify config file
mailiam push --config custom.config.yaml

# Environment targeting
mailiam push --env staging

# JSON output
mailiam status --output json

# Force operation
mailiam domains verify mysite.com --force

Configuration Options

# View current config
mailiam config list

# Set global options
mailiam config set editor vim
mailiam config set timeout 30000
mailiam config set region us-east-1

# Reset config to defaults
mailiam config reset

Workflow Examples

New Project Workflow

# 1. Initialize project
mkdir mycompany.com
cd mycompany.com
mailiam init mycompany.com

# 2. Edit configuration
vim mailiam.config.yaml

# 3. Deploy
mailiam push

# 4. Verify setup
mailiam status
mailiam domains verify mycompany.com

# 5. Test
mailiam domains test mycompany.com test@mycompany.com

Collection-Based Workflow

# 1. Create collection
mailiam collections create "support" "Support Forms"

# 2. Add forms to collection
mailiam collections add-form "support" "technical" "Technical Support"
mailiam collections add-form "support" "billing" "Billing Questions"

# 3. Configure collection
mailiam collections update "support" --rate-limit 50

# 4. Deploy
mailiam push

# 5. Use collection forms
# https://api.mailiam.dev/f/support/technical
# https://api.mailiam.dev/f/support/billing

Migration Workflow

# 1. Import existing instant form
mailiam forms list  # Find form ID
mailiam collections import "mycompany" abc123def "contact"

# 2. Update configuration
mailiam pull  # Sync config file

# 3. Verify migration
mailiam collections show "mycompany"

# 4. Test new endpoint
mailiam forms test mycompany/contact --data '{"email":"test@test.com"}'

Development Workflow

Local Development

# 1. Clone project config
git clone git@github.com:company/email-config.git
cd email-config

# 2. Switch to development
mailiam pull --env dev

# 3. Make changes
vim mailiam.config.dev.yaml

# 4. Test locally
mailiam push --env dev --dry-run

# 5. Deploy to dev
mailiam push --env dev

# 6. Commit changes
git add mailiam.config.dev.yaml
git commit -m "Add new contact form"
git push

Team Collaboration

# Pull latest configuration
mailiam pull

# Check for conflicts
mailiam status

# Merge upstream changes
git pull origin main
mailiam pull --force  # Override local changes

# Deploy team changes
mailiam push

Monitoring and Debugging

Status Monitoring

# Overall system status
mailiam status

# Domain-specific status
mailiam domains status mysite.com

# Form performance
mailiam forms performance contact

# Collection metrics
mailiam collections metrics support

Logging and Debugging

# View recent logs
mailiam logs --last 1h

# Form submission logs
mailiam logs forms contact --last 24h

# Email forwarding logs
mailiam logs forwarding mysite.com

# Error logs only
mailiam logs --level error --last 1d

# Follow logs in real-time
mailiam logs --follow

Testing and Validation

# Test configuration syntax
mailiam config validate

# Test domain setup
mailiam domains test mysite.com

# Test form submission
mailiam forms test contact --data file.json

# Test email forwarding
mailiam domains test-email mysite.com test@mysite.com

# Comprehensive health check
mailiam health-check

Performance and Optimization

Performance Monitoring

# Response time metrics
mailiam metrics response-times --last 7d

# Throughput statistics
mailiam metrics throughput forms

# Regional performance
mailiam metrics regions

# Error rates
mailiam metrics errors --all

Optimization Commands

# Enable caching
mailiam forms update contact --caching true

# Optimize templates
mailiam templates optimize

# Prefetch static assets
mailiam performance prefetch --enable

# Check optimization recommendations
mailiam optimize analyze

Advanced Features

Scripting and Automation

# JSON output for scripting
FORMS=$(mailiam forms list --output json)
echo $FORMS | jq '.[] | .id'

# Bulk operations
mailiam forms list --output json | jq -r '.[].id' | xargs -I {} mailiam forms update {} --caching true

# Conditional deployments
if mailiam config validate --quiet; then
  mailiam push
else
  echo "Configuration validation failed"
  exit 1
fi

CI/CD Integration

# GitLab CI example
deploy:
  script:
    - npm install -g mailiam
    - mailiam config validate
    - mailiam push --env production
  only:
    - main

# GitHub Actions example
- name: Deploy Email Config
  run: |
    mailiam config validate
    mailiam push --env production
  env:
    MAILIAM_API_KEY: ${{ secrets.MAILIAM_API_KEY }}

Configuration Management

# Environment-specific secrets
mailiam secrets set DATABASE_URL "postgres://..." --env dev
mailiam secrets set DATABASE_URL "postgres://..." --env production

# Template variables
mailiam templates set-var COMPANY_NAME "My Company" --env production
mailiam templates set-var SUPPORT_EMAIL "help@company.com" --env production

# Feature flags
mailiam config set features.newTemplateEngine true --env staging

Help and Documentation

Built-in Help

# General help
mailiam --help

# Command-specific help
mailiam forms --help
mailiam collections create --help

# Examples for commands
mailiam forms create --examples

# Configuration reference
mailiam config schema

Version Information

# CLI version
mailiam --version

# Detailed version info
mailiam version --verbose

# Check for updates
mailiam update-check

# Update CLI
npm update -g mailiam

The mailiam CLI transforms email infrastructure management from a chore into a streamlined, version-controlled workflow that developers actually enjoy using.