| name | loops-cli |
| description | Use the Loops CLI to manage contacts, send events, trigger transactional emails, manage mailing lists, and interact with the Loops (loops.so) email marketing platform. Use when the user asks to interact with Loops, manage email contacts, send transactional emails, or query mailing lists from the command line. |
Loops CLI
Unofficial CLI for Loops with full API parity. Optimized for both developers and AI agents.
When to use
Use this CLI when you need to:
- Create, update, find, or delete contacts in Loops
- Send events to trigger automated email workflows
- Send transactional emails with dynamic data variables
- List and manage mailing lists
- Manage custom contact properties
- Test API key validity
- Script or automate Loops email workflows from the terminal
Install
npm install -g @miketromba/loops-cli
The CLI is also available via npx @miketromba/loops-cli, or install with yarn/pnpm/bun.
Authentication
loops auth login --api-key <your-api-key>
export LOOPS_API_KEY=your_api_key_here
Get an API key at https://app.loops.so/settings?page=api
Check auth status:
loops auth status
Command grammar
All commands follow this pattern:
loops <resource> <action> [--flags]
Examples:
loops contacts create --email user@example.com
loops contacts find --email user@example.com
loops mailing-lists list
loops events send --email user@example.com --event-name signup
loops transactional send --transactional-id txn_123 --email user@example.com
Run loops --help for all resources. Run loops <resource> --help for actions and examples.
Output formats
The CLI auto-detects the environment:
| Context | Default format | Description |
|---|
| TTY (interactive) | table | Human-readable columns with color |
| Piped / non-TTY | compact | key=value one-liners, minimal tokens |
Override with -o <format>:
| Format | Flag | Use case |
|---|
| compact | -o compact | AI agents, scripting |
| json | -o json | Programmatic consumption |
| jsonl | -o jsonl | Streaming, jq pipelines |
| csv | -o csv | Export, spreadsheets |
| tsv | -o tsv | Unix tools (cut, awk) |
| id | -o id | Pipe IDs to other commands |
| count | -o count | "How many?" queries |
| table | -o table | Human-readable |
Parsing compact output
Compact format is optimized for AI agents:
mailingLists 1-2/2 page=1
[1] id=list_123 name=Newsletter isPublic=true
[2] id=list_456 name=Updates isPublic=false
Field selection
loops contacts find --email user@example.com --fields id,email,firstName
loops mailing-lists list --detail
Common workflows
Manage contacts
loops contacts create --email user@example.com
loops contacts create --email user@example.com --properties '{"firstName":"Jane","lastName":"Doe"}'
loops contacts create --email user@example.com --mailing-lists '{"list_id":true}'
loops contacts update --email user@example.com --properties '{"firstName":"Updated"}'
loops contacts update --user-id usr_123 --properties '{"plan":"pro"}'
loops contacts find --email user@example.com
loops contacts find --user-id usr_123
loops contacts delete --email user@example.com
loops contacts delete --user-id usr_123
Send events
loops events send --email user@example.com --event-name signup
loops events send --email user@example.com --event-name purchase --event-properties '{"plan":"pro","amount":29}'
Send transactional emails
loops transactional list
loops transactional send --transactional-id txn_123 --email user@example.com --data-variables '{"name":"Jane","url":"https://example.com"}'
Mailing lists
loops mailing-lists list
loops mailing-lists list --output json
Contact properties
loops contact-properties list
loops contact-properties create --name favoriteColor --type string
Pipe patterns
loops mailing-lists list -o id
loops mailing-lists list -o count
loops mailing-lists list -o json > lists.json
loops transactional list -o jsonl | jq '.name'
Environment variables
| Variable | Purpose |
|---|
LOOPS_API_KEY | API key (overrides stored credential) |
LOOPS_OUTPUT | Default output format |
Key global flags
| Flag | Short | Description |
|---|
--output <format> | -o | Output format |
--fields <list> | -f | Comma-separated field selection |
--detail | -d | Full detail view |
--yes | -y | Skip confirmation prompts |
--quiet | -q | Data only, no hints or headers |
--no-color | | Disable color output |
--verbose | | Debug output to stderr |
Resources
For the full list of resources and their operations, see references/COMMANDS.md.
Official Loops documentation
For deeper understanding of Loops platform concepts, API behaviors, or feature guides, fetch the official docs index:
https://loops.so/docs/llms.txt
This is a machine-readable index of all Loops documentation. Use it when you need to:
- Understand how a Loops feature works (e.g., transactional emails, events, mailing lists)
- Check API rate limits and error handling
- Look up contact property types and formats
- Find guides for specific workflows
