CLI Troubleshooting

CLI Troubleshooting

Common issues and solutions when working with the mailiam CLI.

Installation Issues

Command Not Found

Problem: mailiam: command not found

Solution:

# Verify installation
npm list -g mailiam

# Reinstall if needed
npm install -g mailiam

# Check PATH includes npm global bin
npm bin -g
echo $PATH

Permission Errors on macOS/Linux

Problem: Permission denied during installation

Solution:

# Use npm prefix to avoid sudo
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

# Add to shell profile
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

# Install CLI
npm install -g mailiam

Node.js Version Issues

Problem: CLI requires Node.js 16+

Solution:

# Check Node version
node --version

# Update Node.js using nvm
nvm install 18
nvm use 18

# Or download from nodejs.org

Authentication Issues

API Key Not Working

Problem: Invalid API key or Authentication failed

Solution:

1. Check your API key format:

   # Should start with mlm_
   mailiam auth status

2. Verify the key in your dashboard

3. Try setting a new key:

   mailiam auth set-key YOUR_NEW_API_KEY

Environment Variable Not Found

Problem: CLI doesn’t find MAILIAM_API_KEY

Solution:

# Check if variable is set
echo $MAILIAM_API_KEY

# Set temporarily
export MAILIAM_API_KEY=your_key_here

# Set permanently in shell profile
echo 'export MAILIAM_API_KEY=your_key' >> ~/.bashrc
source ~/.bashrc

Credential Storage Issues

Problem: CLI can’t store credentials

Solution:

macOS:

# Keychain permission issues
security find-generic-password -s "mailiam-cli"
# Grant access when prompted

Linux:

# Install libsecret
sudo apt-get install libsecret-1-dev
# or
sudo yum install libsecret-devel

Windows:

# Run as administrator if needed
# Check Windows Credential Manager

Configuration Issues

Config File Not Found

Problem: No configuration file found

Solution:

# Initialize configuration
mailiam init

# Or create manually
touch mailiam.config.yaml

YAML Syntax Errors

Problem: YAML parsing error

Solution:

# Validate YAML syntax
mailiam test config

# Common issues:
# - Indentation (use spaces, not tabs)
# - Missing colons
# - Unquoted special characters

Valid YAML example:

project:
  name: "My App"
  slug: "my-app"

domains:
  example.com:
    forwarding:
      "hello@example.com": "team@company.com"

Project Not Found

Problem: Project not found when pushing

Solution:

# Check project configuration
mailiam auth status

# Re-initialize if needed
mailiam init --force

# Or set project ID manually in config

Domain Issues

Domain Verification Failed

Problem: Domain verification fails

Solution:

1. Check DNS propagation:

   dig TXT _mailiam.yourdomain.com
   nslookup -type=TXT _mailiam.yourdomain.com

2. Verify DNS record is correct:

   mailiam domains verify yourdomain.com --debug

3. Wait for DNS propagation (up to 48 hours)

DNS Sync Issues

Problem: DNS sync fails with Cloudflare

Solution:

# Check provider credentials
mailiam providers test cloudflare

# Re-add provider if needed
mailiam providers add cloudflare

# Verify zone access
mailiam domains sync yourdomain.com --dry-run

SES Verification Problems

Problem: AWS SES verification fails

Solution:

1. Check AWS region:

   # Ensure you're in the correct region
   mailiam domains ses-status yourdomain.com

2. Verify DNS records:

   mailiam domains setup-ses yourdomain.com
   # Add the returned DNS records

3. Check SES limits:

   # Ensure you're not in SES sandbox
   # Request production access if needed

Network Issues

Connection Timeouts

Problem: CLI timeouts or network errors

Solution:

# Check connectivity
ping api.mailiam.dev
curl -I https://api.mailiam.dev

# Set proxy if needed
export HTTP_PROXY=http://proxy:8080
export HTTPS_PROXY=http://proxy:8080

Firewall Issues

Problem: Corporate firewall blocking requests

Solution:

1. Whitelist domains:

   • api.mailiam.dev
   • mail.mailiam.dev

2. Configure proxy:

   mailiam config set proxy http://proxy:8080

3. Use alternative endpoint (if available):

   export MAILIAM_API_URL=https://alternative-api.mailiam.dev

Form and Email Issues

Forms Not Working

Problem: Form submissions failing

Solution:

1. Check form endpoint:

   mailiam domains status
   # Verify the correct endpoint URL

2. Test form locally:

   curl -X POST https://api.mailiam.dev/yourdomain.com/send \
     -F "name=Test" \
     -F "email=test@example.com" \
     -F "message=Test message"

3. Check CORS configuration for browser submissions

Email Not Being Sent

Problem: Emails not arriving

Solution:

1. Check spam folders

2. Verify email configuration:

   mailiam test send your@email.com

3. Check domain SES status:

   mailiam domains ses-status yourdomain.com

Template Issues

Problem: Email templates not working

Solution:

1. Validate template files exist

2. Check template syntax:

   mailiam templates preview template-name

3. Verify template variables are correct

Performance Issues

Slow CLI Commands

Problem: CLI commands are slow

Solution:

# Clear CLI cache
rm -rf ~/.mailiam/cache

# Use debug mode to identify bottlenecks
mailiam push --debug

# Check network connectivity
ping api.mailiam.dev

Large Configuration Files

Problem: Config file too large

Solution:

• Split configurations into multiple files
• Use collections for organizing forms
• Remove unused templates/domains

Debugging Commands

Enable Debug Mode

# Enable detailed logging
mailiam push --debug
mailiam domains verify yourdomain.com --debug

# Or set environment variable
export MAILIAM_DEBUG=true

Check CLI Version

# Verify CLI version
mailiam --version

# Update to latest
npm update -g mailiam

Validate Configuration

# Test configuration syntax
mailiam test config

# Dry run deployment
mailiam push --dry-run

Getting Help

Documentation Resources

• CLI Commands
• Configuration Reference
• API Documentation

Support Channels

1. GitHub Issues: Report bugs and feature requests
2. Email Support: support@mailiam.dev
3. Discord Community: Join our Discord server
4. Documentation: https://mailiam.dev/docs

Before Contacting Support

Please include:

• CLI version: mailiam --version
• Node.js version: node --version
• Operating system
• Error messages (with --debug flag)
• Configuration file (remove sensitive data)

Common Error Messages

”Project not found”

• Initialize project: mailiam init
• Check API key has correct permissions

”Domain not verified”

• Run: mailiam domains verify yourdomain.com
• Check DNS records are properly set

”Rate limit exceeded”

• Wait before retrying
• Contact support if limits seem incorrect

”Invalid template”

• Check template file paths
• Verify template syntax

”DNS sync failed”

• Check provider credentials
• Verify domain is in Cloudflare zone
• Use --dry-run to preview changes first

Still Need Help?

If you can’t find a solution here:

1. Search existing GitHub issues
2. Create a new issue with detailed information
3. Contact support at support@mailiam.dev
4. Join our community Discord for real-time help