mautic-cli 0.1.0

CLI for Mautic marketing automation - built for humans and AI agents.

mautic-cli

CLI for Mautic marketing automation - built for humans and AI agents.

Quick Start · Commands · Output Formats · AI Agents

---

What it does

Category	Capabilities
Contacts	List, search, create, edit, delete, points, segments, campaigns, activity
Segments	List, create, edit, delete, add/remove contacts
Emails	List, create, edit, send to contact, send to segment
Campaigns	List, create, edit, delete, clone (7+), add/remove contacts
Auth	Basic Auth, OAuth2 Client Credentials, multiple profiles
Output	JSON, colored tables, CSV, NDJSON streaming

Quick Start

# Install (pick one)
uv tool install mautic-cli    # recommended
pip install mautic-cli         # or with pip
pipx install mautic-cli        # or with pipx

# Authenticate
mautic auth setup

# Use it
mautic contacts list --limit 5
mautic --format table emails list

Commands

Contacts

mautic contacts list --search "email:*@company.com" --limit 50
mautic contacts get 42
mautic contacts create --json '{"firstname":"Ana","email":"[e-mail]"}'
mautic contacts edit 42 --json '{"lastname":"Silva"}'
mautic contacts delete 42
mautic contacts add-points 42 10
mautic contacts add-to-segment 42 5
mautic contacts activity 42

Segments

mautic segments list
mautic segments get 1
mautic segments contacts 1
mautic segments create --json '{"name":"Newsletter Q1","isPublished":true}'

Emails

mautic emails list
mautic emails get 1
mautic emails send 1 --contact 42
mautic emails send-to-segment 1

Campaigns

mautic campaigns list
mautic campaigns get 1
mautic campaigns contacts 1
mautic campaigns clone 1    # Mautic 7+ only

All write commands accept JSON from inline, file, or stdin

mautic contacts create --json '{"email":"[e-mail]"}'
mautic contacts create --json @contact.json
cat contact.json | mautic contacts create --json @-

Output Formats

Table - colored, aligned columns with total count (powered by rich):

                     Showing 5 of 274,528
id      firstname  lastname  email               points  dateAdded
66515   Lidia      Duarte    [e-mail]    0       2024-09-27
26698   Claudia    Preis     [e-mail]  0       2024-08-25

mautic --format table contacts list --limit 5

JSON (default) - full API response, pretty-printed in terminal:

mautic contacts list --limit 5

CSV - same key fields, pipe to file:

mautic --format csv contacts list > contacts.csv

NDJSON - one JSON object per line, auto-paginating through all results:

mautic --page-all contacts list | jq '.fields.all.email'

Global Flags

Global flags go before the resource group:

mautic --format table --published-only emails list

Flag	Description
--format json|table|csv	Output format (default: json)
--pretty	Pretty-print JSON
--page-all	Auto-paginate, output NDJSON per record
--dry-run	Show HTTP request without executing
--verbose	Show HTTP request/response details
--published-only	Filter to published items only
--no-verify-ssl	Skip SSL certificate verification
--profile <name>	Use a named config profile

Authentication

Interactive Setup

mautic auth setup    # Prompts for URL, method (basic/oauth2), credentials
mautic auth test     # Verify connection and detect Mautic version

Supports Basic Auth and OAuth2 Client Credentials grant.

Environment Variables

export MAUTIC_BASE_URL=https://mautic.example.com
export MAUTIC_USERNAME=admin
export MAUTIC_PASSWORD=secret

Profiles

Manage multiple Mautic instances with named profiles:

mautic auth setup           # Profile name: production
mautic auth setup           # Profile name: staging
mautic auth list            # Show all profiles
mautic auth delete staging  # Remove a profile

mautic --profile staging contacts list

SSL / self-signed certificates (DDEV, local dev)

# Per-command
mautic --no-verify-ssl contacts list

# Or save the preference during auth setup
mautic auth setup
# Skip SSL verification? (for self-signed certs) [y/N]: y

Search Syntax

The --search flag passes through to Mautic's native search:

mautic contacts list --search "email:*@company.com"
mautic emails list --search "name:Newsletter"
mautic --published-only segments list    # uses is:published internally

Shell Completion

Tab-completion for all commands, subcommands, and options:

mautic completion    # Shows install instructions for your shell

AI Agents

mautic-cli ships with an agent skill that teaches AI coding agents the full command reference, auth flow, and safety rules for write operations.

Install with npx skills (supports Claude Code, Cursor, Codex, Gemini, Windsurf, and 37+ agents):

npx skills add https://github.com/bloomidea/mautic-cli

Then ask your agent: "list my mautic contacts" or "send email 5 to contact 42".

License

MIT