CLI

On this page:

• Installation
• Authentication
• Usage
• Sending data
• Output formats
• Filtering & pagination
• AI Skill
• Debugging

Installation#

Install the CLI globally using Composer:

composer global require spatie/mailcoach-cli

Verify the installation:

mailcoach --version

Authentication#

Before using the CLI, you need to authenticate with your Mailcoach instance:

mailcoach login

This will prompt you for your API token and instance URL. Your credentials are stored in ~/.mailcoach/config.json. This works with both Mailcoach Cloud and self-hosted instances.

To remove your stored credentials:

mailcoach logout

Usage#

All commands are auto-generated from the Mailcoach OpenAPI spec. To see all available commands:

mailcoach list

Commands follow a consistent CRUD pattern using kebab-case names:

# Email lists
mailcoach list-email-lists
mailcoach create-email-list --field name="Newsletter" --field default_from_email="hi@example.com"
mailcoach show-email-list --email-list=<uuid>

# Subscribers
mailcoach list-subscribers --email-list=<uuid>
mailcoach create-subscriber --email-list=<uuid> --field email="john@example.com" --field first_name="John"

# Campaigns
mailcoach list-campaigns
mailcoach create-campaign --input '{"name": "March update", "email_list_uuid": "<uuid>"}'
mailcoach send-campaign --campaign=<uuid>
mailcoach send-campaign-test --campaign=<uuid> --field email="test@example.com"

Other available resources include: tags, segments, templates, automations, transactional emails, and suppressions.

Sending data#

There are two ways to send data with your commands:

JSON input (for complex or nested data):

mailcoach create-email-list --input '{"name": "Newsletter", "default_from_email": "hi@example.com"}'

Field flags (for simple flat data):

mailcoach create-email-list --field name="Newsletter" --field default_from_email="hi@example.com"

File uploads (prefix the path with @):

mailcoach create-subscriber-import --email-list=<uuid> --field csv=@/path/to/subscribers.csv

Output formats#

By default, commands return human-readable output. You can change the format:

# Raw JSON (useful for piping or extracting UUIDs)
mailcoach list-email-lists --json

# YAML output
mailcoach list-email-lists --yaml

# Minified single-line JSON
mailcoach list-email-lists --minify

# Include HTTP response headers
mailcoach list-email-lists -H

Filtering & pagination#

Most list commands support filtering and pagination:

mailcoach list-subscribers --email-list=<uuid> \
  --filter-search="john" \
  --filter-status=subscribed \
  --sort=-created_at \
  --filter-per-page=100 \
  --filter-page=1

AI Skill#

The CLI ships with an AI Skill that lets AI agents like Claude Code, Cursor, and GitHub Copilot manage your Mailcoach instance.

Via Laravel Boost (in a Laravel project):

composer require spatie/mailcoach-cli --dev
php artisan boost:install

Via skills.sh:

npx skills add spatie/mailcoach-cli

Manual installation:

Copy the skill files from the package’s resources/boost/skills/mailcoach/ directory to your project:

• Claude Code: .claude/skills/mailcoach/
• Cursor: .cursor/skills/mailcoach/
• Other agents: .ai/skills/mailcoach/

Once installed, your AI agent can manage email lists, subscribers, campaigns, templates, transactional emails, and automations through natural language.

Debugging#

Use the verbose flag to see the full HTTP request and response details:

mailcoach list-email-lists -vvv

The CLI caches the OpenAPI spec for 24 hours. To force a refresh:

mailcoach clear-cache