CLI Authentication

Learn how to authenticate with the mailiam CLI and manage your API credentials securely.

Installation

First, install the mailiam CLI globally:

npm install -g mailiam

Getting Started

1. Create a mailiam Account

If you don’t have an account yet, create one using the CLI:

mailiam signup

This will guide you through creating your account and provide you with an API key.

2. Set Your API Key

Once you have your API key, configure it with the CLI:

mailiam auth set-key YOUR_API_KEY

The API key will be stored securely in your system’s credential store.

Authentication Methods

Global API Key (Recommended)

Set your API key globally to use across all projects:

mailiam auth set-key mlm_your_api_key_here

Environment Variable

Alternatively, set the API key as an environment variable:

export MAILIAM_API_KEY=mlm_your_api_key_here

Add this to your shell profile (.bashrc, .zshrc, etc.) to make it persistent.

Project-Specific Configuration

For project-specific setups, you can also set the API key in your project directory:

cd your-project
mailiam auth set-key YOUR_API_KEY --local

Managing Authentication

Check Authentication Status

Verify your authentication is working:

mailiam auth status

This command shows:

Whether you’re authenticated
Which API key is being used (masked for security)
Your account information

View Authentication Help

Get detailed help for authentication commands:

mailiam auth --help

Available authentication commands:

mailiam auth set-key <key> - Set your API key
mailiam auth status - Check authentication status
mailiam auth clear - Remove stored credentials

API Key Format

mailiam API keys follow this format:

Prefix: mlm_
Length: 32+ characters
Example: mlm_sk_abc123def456...

Security Best Practices

1. Keep API Keys Secure

Never commit API keys to version control
Use environment variables in production
Rotate keys regularly
Don’t share keys via insecure channels

2. Environment-Specific Keys

Use different API keys for different environments:

# Development
export MAILIAM_API_KEY=mlm_dev_your_dev_key

# Production
export MAILIAM_API_KEY=mlm_prod_your_prod_key

3. Team Management

For teams, each developer should have their own API key. Don’t share keys between team members.

Credential Storage

Where Credentials Are Stored

The mailiam CLI stores credentials securely using your operating system’s credential store:

macOS: Keychain Access
Windows: Windows Credential Manager
Linux: Secret Service API (libsecret)

Manual Credential Management

If needed, you can manually manage credentials:

# Clear stored credentials
mailiam auth clear

# Re-authenticate
mailiam auth set-key YOUR_NEW_API_KEY

Troubleshooting Authentication

Common Issues

“API key not found” error

# Check if key is set
mailiam auth status

# Set your API key
mailiam auth set-key YOUR_API_KEY

“Invalid API key” error

Verify your API key is correct
Check if the key has expired
Ensure you have the correct permissions

“Authentication failed” error

Check your internet connection
Verify the API endpoint is accessible
Try setting the key again

Network Configuration

If you’re behind a corporate firewall or proxy:

# Set proxy (if needed)
export HTTP_PROXY=http://your-proxy:8080
export HTTPS_PROXY=http://your-proxy:8080

# Then authenticate
mailiam auth set-key YOUR_API_KEY

Getting Help

If you continue to have authentication issues:

Check your API key in the mailiam dashboard
Try creating a new API key
Contact support at support@mailiam.dev
Run mailiam auth status --debug for detailed error information

Integration with CI/CD

GitHub Actions

name: Deploy mailiam Config
on: [push]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install mailiam CLI
        run: npm install -g mailiam
      - name: Deploy configuration
        env:
          MAILIAM_API_KEY: ${{ secrets.MAILIAM_API_KEY }}
        run: mailiam push

Other CI Systems

For other CI systems, set MAILIAM_API_KEY as a secret environment variable and the CLI will automatically use it.

Next Steps

Once authenticated, you can: