Skip to content

Commit 7829b18

Browse files
introfiniintrofini
committed
feat: mautic-cli v0.1.0 - CLI for Mautic marketing automation
Built for humans and AI agents. Supports Mautic 4.x-7.x via REST API. - Contacts, segments, emails, campaigns CRUD - Basic Auth and OAuth2 Client Credentials - JSON, colored tables (rich), CSV, NDJSON output - Auto-pagination, search, dry-run, verbose mode - Multiple profiles for different Mautic instances - Shell completion (bash/zsh/fish) - Agent skill for Claude Code, Cursor, Codex, and 37+ AI agents
0 parents  commit 7829b18

32 files changed

Lines changed: 3189 additions & 0 deletions

‎.gitignore‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
__pycache__/
2+
*.py[cod]
3+
*.egg-info/
4+
dist/
5+
build/
6+
.eggs/
7+
.pytest_cache/
8+
*.egg
9+
.venv/
10+
11+
.claude/
12+
mantic-MCP/

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Bloomidea
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
<div align="center">
2+
3+
# mautic-cli
4+
5+
**CLI for Mautic marketing automation - built for humans and AI agents.**
6+
7+
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
8+
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-3776AB.svg)](https://python.org)
9+
[![Mautic 4.x-7.x](https://img.shields.io/badge/mautic-4.x--7.x-4e5e9e.svg)](https://mautic.org)
10+
11+
[Quick Start](#quick-start) &#183; [Commands](#commands) &#183; [Output Formats](#output-formats) &#183; [AI Agents](#ai-agents)
12+
13+
</div>
14+
15+
---
16+
17+
## What it does
18+
19+
| Category | Capabilities |
20+
|----------|-------------|
21+
| **Contacts** | List, search, create, edit, delete, points, segments, campaigns, activity |
22+
| **Segments** | List, create, edit, delete, add/remove contacts |
23+
| **Emails** | List, create, edit, send to contact, send to segment |
24+
| **Campaigns** | List, create, edit, delete, clone (7+), add/remove contacts |
25+
| **Auth** | Basic Auth, OAuth2 Client Credentials, multiple profiles |
26+
| **Output** | JSON, colored tables, CSV, NDJSON streaming |
27+
28+
## Quick Start
29+
30+
```bash
31+
# Install (pick one)
32+
uv tool install mautic-cli # recommended
33+
pip install mautic-cli # or with pip
34+
pipx install mautic-cli # or with pipx
35+
36+
# Authenticate
37+
mautic auth setup
38+
39+
# Use it
40+
mautic contacts list --limit 5
41+
mautic --format table emails list
42+
```
43+
44+
## Commands
45+
46+
### Contacts
47+
48+
```bash
49+
mautic contacts list --search "email:*@company.com" --limit 50
50+
mautic contacts get 42
51+
mautic contacts create --json '{"firstname":"Ana","email":"ana@example.com"}'
52+
mautic contacts edit 42 --json '{"lastname":"Silva"}'
53+
mautic contacts delete 42
54+
mautic contacts add-points 42 10
55+
mautic contacts add-to-segment 42 5
56+
mautic contacts activity 42
57+
```
58+
59+
### Segments
60+
61+
```bash
62+
mautic segments list
63+
mautic segments get 1
64+
mautic segments contacts 1
65+
mautic segments create --json '{"name":"Newsletter Q1","isPublished":true}'
66+
```
67+
68+
### Emails
69+
70+
```bash
71+
mautic emails list
72+
mautic emails get 1
73+
mautic emails send 1 --contact 42
74+
mautic emails send-to-segment 1
75+
```
76+
77+
### Campaigns
78+
79+
```bash
80+
mautic campaigns list
81+
mautic campaigns get 1
82+
mautic campaigns contacts 1
83+
mautic campaigns clone 1 # Mautic 7+ only
84+
```
85+
86+
<details>
87+
<summary><strong>All write commands accept JSON from inline, file, or stdin</strong></summary>
88+
89+
```bash
90+
mautic contacts create --json '{"email":"test@example.com"}'
91+
mautic contacts create --json @contact.json
92+
cat contact.json | mautic contacts create --json @-
93+
```
94+
</details>
95+
96+
## Output Formats
97+
98+
**Table** - colored, aligned columns with total count (powered by [rich](https://github.com/Textualize/rich)):
99+
100+
```
101+
Showing 5 of 274,528
102+
id firstname lastname email points dateAdded
103+
66515 Lidia Duarte lidia@example.com 0 2024-09-27
104+
26698 Claudia Preis claudia@example.com 0 2024-08-25
105+
```
106+
107+
```bash
108+
mautic --format table contacts list --limit 5
109+
```
110+
111+
**JSON** (default) - full API response, pretty-printed in terminal:
112+
113+
```bash
114+
mautic contacts list --limit 5
115+
```
116+
117+
**CSV** - same key fields, pipe to file:
118+
119+
```bash
120+
mautic --format csv contacts list > contacts.csv
121+
```
122+
123+
**NDJSON** - one JSON object per line, auto-paginating through all results:
124+
125+
```bash
126+
mautic --page-all contacts list | jq '.fields.all.email'
127+
```
128+
129+
## Global Flags
130+
131+
Global flags go **before** the resource group:
132+
133+
```bash
134+
mautic --format table --published-only emails list
135+
```
136+
137+
| Flag | Description |
138+
|----------|-------------|
139+
| `--format json\|table\|csv` | Output format (default: json) |
140+
| `--pretty` | Pretty-print JSON |
141+
| `--page-all` | Auto-paginate, output NDJSON per record |
142+
| `--dry-run` | Show HTTP request without executing |
143+
| `--verbose` | Show HTTP request/response details |
144+
| `--published-only` | Filter to published items only |
145+
| `--no-verify-ssl` | Skip SSL certificate verification |
146+
| `--profile <name>` | Use a named config profile |
147+
148+
## Authentication
149+
150+
### Interactive Setup
151+
152+
```bash
153+
mautic auth setup # Prompts for URL, method (basic/oauth2), credentials
154+
mautic auth test # Verify connection and detect Mautic version
155+
```
156+
157+
Supports **Basic Auth** and **OAuth2 Client Credentials** grant.
158+
159+
### Environment Variables
160+
161+
```bash
162+
export MAUTIC_BASE_URL=https://mautic.example.com
163+
export MAUTIC_USERNAME=admin
164+
export MAUTIC_PASSWORD=secret
165+
```
166+
167+
### Profiles
168+
169+
Manage multiple Mautic instances with named profiles:
170+
171+
```bash
172+
mautic auth setup # Profile name: production
173+
mautic auth setup # Profile name: staging
174+
mautic auth list # Show all profiles
175+
mautic auth delete staging # Remove a profile
176+
177+
mautic --profile staging contacts list
178+
```
179+
180+
<details>
181+
<summary><strong>SSL / self-signed certificates (DDEV, local dev)</strong></summary>
182+
183+
```bash
184+
# Per-command
185+
mautic --no-verify-ssl contacts list
186+
187+
# Or save the preference during auth setup
188+
mautic auth setup
189+
# Skip SSL verification? (for self-signed certs) [y/N]: y
190+
```
191+
</details>
192+
193+
## Search Syntax
194+
195+
The `--search` flag passes through to [Mautic's native search](https://docs.mautic.org/en/5.x/contacts/search.html):
196+
197+
```bash
198+
mautic contacts list --search "email:*@company.com"
199+
mautic emails list --search "name:Newsletter"
200+
mautic --published-only segments list # uses is:published internally
201+
```
202+
203+
## Shell Completion
204+
205+
Tab-completion for all commands, subcommands, and options:
206+
207+
```bash
208+
mautic completion # Shows install instructions for your shell
209+
```
210+
211+
## AI Agents
212+
213+
mautic-cli ships with an [agent skill](skills/mautic/SKILL.md) that teaches AI coding agents the full command reference, auth flow, and safety rules for write operations.
214+
215+
Install with [`npx skills`](https://github.com/vercel-labs/skills) (supports Claude Code, Cursor, Codex, Gemini, Windsurf, and [37+ agents](https://add-skill.org/)):
216+
217+
```bash
218+
npx skills add https://github.com/bloomidea/mautic-cli
219+
```
220+
221+
Then ask your agent: *"list my mautic contacts"* or *"send email 5 to contact 42"*.
222+
223+
## License
224+
225+
[MIT](LICENSE)

‎pyproject.toml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
[build-system]
2+
requires = ["setuptools>=68.0"]
3+
build-backend = "setuptools.build_meta"
4+
5+
[project]
6+
name = "mautic-cli"
7+
version = "0.1.0"
8+
description = "CLI for Mautic marketing automation - built for humans and AI agents."
9+
readme = "README.md"
10+
license = "MIT"
11+
requires-python = ">=3.11"
12+
dependencies = [
13+
"click>=8.1",
14+
"httpx>=0.27",
15+
"rich>=13.0",
16+
]
17+
18+
[project.optional-dependencies]
19+
dev = [
20+
"pytest>=8.0",
21+
"respx>=0.22",
22+
]
23+
24+
[project.scripts]
25+
mautic = "mautic_cli.cli:cli"
26+
27+
[tool.setuptools.packages.find]
28+
where = ["src"]

0 commit comments

Comments
 (0)