# Bento CLI

Manage your Bento email marketing directly from the terminal.

The Bento CLI is a command-line interface with 50+ commands that lets you manage your entire Bento account from the terminal. Search subscribers, import from CSV, manage tags and fields, track events and purchases, create broadcasts and sequences, send transactional emails, manage templates, and more.

Perfect for automation scripts, CI/CD pipelines, multi-account management, or anyone who prefers working in the terminal.

---


> **Before you begin, make sure you have:**
> - A Bento account with API access
> - Your Bento API credentials (Publishable Key, Secret Key, Site UUID)
> - Node.js 18 or later installed on your machine


---


## Installation


Install the Bento CLI globally using npm or Bun:


  
  


Verify the installation:

```bash
bento --version
```

---


## Authentication


Before using the CLI, you need to authenticate with your Bento account.


**1. Get Your API Credentials**


Log into your Bento account and go to [Team Settings](https://app.bentonow.com/account/teams) to find your API keys.

You'll need:
- **Publishable Key**: `pk_live_abc123...`
- **Secret Key**: `sk_live_xyz789...`
- **Site UUID**: Your unique site identifier


**2. Run the Login Command**


```bash
bento auth login
```

You'll be prompted to enter your credentials. They'll be stored securely for future use.

For scripting or CI/CD, you can pass credentials directly:

```bash
bento auth login \
  --publishable-key "pk_live_..." \
  --secret-key "sk_live_..." \
  --site-uuid "your-site-uuid"
```


**3. Verify Connection**


Test your authentication by listing your tags:

```bash
bento tags list
```

If you see your tags, you're all set!


> 🚨 **Important**
> Keep your Secret Key private! Never commit it to version control or share it publicly.


### Other Auth Commands

```bash
# Check authentication status
bento auth status

# Log out and remove stored credentials
bento auth logout
```

---


## Command Reference


## Profile Management

Manage multiple Bento accounts with named profiles.

### Add a Profile

```bash
# Interactive setup
bento profile add staging

# Non-interactive (for scripting)
bento profile add production \
  --publishable-key "pk_live_..." \
  --secret-key "sk_live_..." \
  --site-uuid "your-site-uuid"
```

### List Profiles

```bash
bento profile list
```

### Switch Profile

```bash
bento profile use staging
```

### Remove a Profile

```bash
bento profile remove staging

# Skip confirmation
bento profile remove staging --yes
```

---

## Dashboard

```bash
# Open Bento dashboard in your browser
bento dashboard

# Open for a specific profile
bento dashboard --profile staging
```

---

## Subscribers

Manage your subscriber list from the command line.

### Search Subscribers

```bash
# Look up by email
bento subscribers search --email "john@example.com"

# Look up by UUID
bento subscribers search --uuid "abc-123-def"

# Filter by tag
bento subscribers search --email "john@example.com" --tag "vip"

# Filter by field value
bento subscribers search --email "john@example.com" --field plan=pro
```

### Import from CSV

Import subscribers in bulk from a CSV file:

```bash
# Preview what will be imported (dry run)
bento subscribers import ./contacts.csv --dry-run

# Preview with sample items
bento subscribers import ./contacts.csv --dry-run --sample 5

# Import with confirmation
bento subscribers import ./contacts.csv --confirm

# Limit to first N rows
bento subscribers import ./contacts.csv --limit 100 --confirm
```

**CSV Format:**
```csv
email,first_name,last_name,company
john@example.com,John,Doe,Acme Corp
jane@example.com,Jane,Smith,Widget Co
```

### Create or Update a Subscriber

```bash
# Create or update with tags and fields
bento subscribers upsert \
  --email "john@example.com" \
  --tags "customer,vip" \
  --fields '{"name": "John", "plan": "pro"}'

# Remove tags while adding others
bento subscribers upsert \
  --email "john@example.com" \
  --tags "active" \
  --remove-tags "trial"
```

### Manage Tags on Subscribers

```bash
# Add tags to a single subscriber
bento subscribers tag --email "john@example.com" --add "VIP,newsletter"

# Remove tags
bento subscribers tag --email "john@example.com" --remove "trial"

# Bulk tag from a file
bento subscribers tag --file users.csv --add "customer,active" --confirm

# Preview bulk tagging
bento subscribers tag --file users.csv --add "vip" --dry-run
```

### Manage Fields on Subscribers

```bash
# Set a single field (does NOT trigger automations)
bento subscribers field set --email "john@example.com" --key plan --value pro

# Remove a field
bento subscribers field remove --email "john@example.com" --key company

# Update multiple fields (TRIGGERS automations)
bento subscribers field update \
  --email "john@example.com" \
  --fields '{"name": "John", "plan": "pro"}'
```


> `field set` does not trigger automations. Use `field update` when you need automation triggers to fire.


### Subscribe / Unsubscribe

```bash
# Single subscriber
bento subscribers subscribe --email "john@example.com"
bento subscribers unsubscribe --email "john@example.com"

# Bulk from file
bento subscribers subscribe --file reactivate.csv --confirm
bento subscribers unsubscribe --file suppression-list.csv --confirm

# Trigger automations on unsubscribe
bento subscribers unsubscribe --email "john@example.com" --trigger-automations
```

### Change Email Address

```bash
bento subscribers change-email --old "old@example.com" --new "new@example.com"
```

---

## Tags

View, create, and delete tags for organizing your subscribers.

### List Tags

```bash
bento tags list

# Filter by name
bento tags list newsletter
```

### Create a Tag

```bash
bento tags create "webinar-attendees"
bento tags create "vip-customers"
```

### Delete a Tag

```bash
bento tags delete "old-tag"

# Skip confirmation
bento tags delete "old-tag" --confirm
```

---

## Custom Fields

Manage custom fields for storing additional subscriber data.

### List Custom Fields

```bash
bento fields list

# Filter by name
bento fields list company
```

### Create a Custom Field

```bash
bento fields create "company_name"
bento fields create "plan_type"
```

---

## Events

Track custom events to trigger automations and record subscriber activity.

### Track an Event

```bash
bento events track --email "user@example.com" --event "completed_onboarding"

# With additional details
bento events track \
  --email "user@example.com" \
  --event "completed_onboarding" \
  --details '{"plan": "pro", "trial_days": 14}'
```

### Track a Purchase

```bash
bento events purchase \
  --email "user@example.com" \
  --amount 4999 \
  --currency USD \
  --key "order_12345" \
  --cart '{"items": [{"product_sku": "SKU123", "product_name": "Widget", "quantity": 2}]}'
```


> Amount is in cents (e.g., 4999 = $49.99). The `--key` must be unique per purchase to prevent double-counting.


### Import Events from JSON

```bash
bento events import events.json
```

**JSON Format:**
```json
[
  {"email": "user@example.com", "type": "signed_up"},
  {"email": "user@example.com", "type": "completed_onboarding", "details": {"plan": "pro"}}
]
```

---

## Broadcasts

Create and manage email broadcasts.

### List Broadcasts

```bash
bento broadcasts list

# Paginate results
bento broadcasts list --page 2 --per-page 10
```

### Create a Broadcast Draft

```bash
bento broadcasts create \
  --name "Spring Newsletter" \
  --subject "Big Announcement!" \
  --content "<h1>Hello!</h1>" \
  --type html \
  --from-name "Your Company" \
  --from-email "hello@yourcompany.com" \
  --include-tags "newsletter,active" \
  --exclude-tags "unsubscribed" \
  --batch-size 5000
```


> Broadcasts are always created as drafts. Review and send them from the Bento dashboard.


---

## Sequences

Manage email sequences and create sequence emails.

### List Sequences

```bash
bento sequences list
```

### Create a Sequence Email

```bash
# With inline HTML
bento sequences create-email \
  --sequence-id "sequence_abc123" \
  --subject "Welcome to Day 2" \
  --html "<h1>Getting Started</h1><p>Here's what to do next...</p>" \
  --delay-interval days \
  --delay-count 1

# From an HTML file
bento sequences create-email \
  --sequence-id "sequence_abc123" \
  --subject "Your Weekly Tips" \
  --html-file ./emails/weekly-tips.html \
  --delay-interval days \
  --delay-count 7 \
  --inbox-snippet "This week's top tips"
```

### Update a Sequence Email

```bash
# Update subject
bento sequences update-email --template-id 12345 --subject "Updated Subject"

# Update HTML from file
bento sequences update-email --template-id 12345 --html-file ./updated.html
```

---

## Transactional Emails

Send individual or batch transactional emails.

### Send a Single Email

```bash
bento emails send \
  --to "user@example.com" \
  --from "info@yourcompany.com" \
  --subject "Order Confirmation" \
  --html-body "<h1>Thanks for your order!</h1>" \
  --personalizations '{"order_id": "12345", "total": "$49.99"}'
```

### Batch Send from JSON

```bash
bento emails send-batch --file batch-emails.json
```

**JSON Format:**
```json
[
  {
    "to": "user1@example.com",
    "from": "info@yourcompany.com",
    "subject": "Welcome!",
    "html_body": "<h1>Hello!</h1>"
  },
  {
    "to": "user2@example.com",
    "from": "info@yourcompany.com",
    "subject": "Welcome!",
    "html_body": "<h1>Hello!</h1>"
  }
]
```

---

## Templates

View and update email templates.

### Get a Template

```bash
bento templates get 12345
```

### Update a Template

```bash
# Update subject
bento templates update 12345 --subject "New Subject Line"

# Update HTML
bento templates update 12345 --html "<h1>Updated Content</h1>"
```

---

## Workflows

View automation workflows.

```bash
bento workflows list
```

---

## Forms

Retrieve form submission responses.

```bash
bento forms responses my_form_id
```

---

## Statistics

Get an overview of your Bento account.

### Site Statistics

```bash
bento stats site
```

### Segment Statistics

```bash
bento stats segment seg_12345
```

### Report Statistics

```bash
bento stats report rep_12345
```

---

## Skills

Install CLI skills into AI agent harnesses like Claude Code, Cursor, and Windsurf.

### List Available Skills

```bash
bento skills list
```

### Install Skills

```bash
# Install all skills to all detected agents
bento skills install

# Install a specific skill
bento skills install --skill bento

# Install for a specific agent
bento skills install --agent claude-code

# Force overwrite existing installations
bento skills install --force
```

---

## Experimental


> ⚠️ **Warning**
> Experimental commands may change or be removed in future versions.


### Validate Email

```bash
bento experimental validate-email user@example.com
bento experimental validate-email user@example.com --ip "203.0.113.1" --name "John Doe"
```

### Guess Gender

```bash
bento experimental guess-gender John
```

### Geolocate IP

```bash
bento experimental geolocate 203.0.113.1
```

### Check Blacklist

```bash
bento experimental blacklist --domain example.com
bento experimental blacklist --ip 203.0.113.1
```

### Content Moderation

```bash
bento experimental moderate "some user-submitted text"
```

---


## Output Formats


The CLI supports multiple output formats for integration with other tools.

### Default (Human-Readable)

```bash
bento subscribers search "john"
```

Outputs a formatted table with colors.

### JSON Output

```bash
bento subscribers search "john" --json
```

Perfect for piping to `jq` or processing in scripts:

```bash
bento subscribers search "john" --json | jq '.email'
```

### Quiet Mode

```bash
bento subscribers import ./contacts.csv --confirm --quiet
```

Only outputs errors—useful for scripts and cron jobs.

---


## Safety Features


The CLI includes built-in safety features for bulk operations:

### Dry Run

Preview what will happen without making changes:

```bash
bento subscribers import ./contacts.csv --dry-run
```

### Limit

Process only the first N items:

```bash
bento subscribers import ./contacts.csv --limit 10 --confirm
```

### Confirmation

Bulk operations require explicit confirmation:

```bash
# This will prompt for confirmation
bento subscribers import ./contacts.csv

# Skip the prompt (for scripting)
bento subscribers import ./contacts.csv --confirm
```

### Sample Preview

Preview a subset of items before committing to a bulk operation:

```bash
bento subscribers import ./contacts.csv --dry-run --sample 5
```

---


## Scripting Examples


### Import Subscribers from Multiple CSVs

```bash
#!/bin/bash
for file in ./imports/*.csv; do
  echo "Importing $file..."
  bento subscribers import "$file" --confirm --quiet
done
echo "Done!"
```

### Daily Stats Report

```bash
#!/bin/bash
# Add to crontab for daily reports
bento stats site --json > "/var/log/bento/stats-$(date +%Y-%m-%d).json"
```

### Tag New Signups

```bash
#!/bin/bash
# Tag a new signup from your app
bento subscribers tag "$EMAIL" --add "new-signup,trial"
bento events track --email "$EMAIL" --event "signed_up" --details "{\"source\": \"$SOURCE\"}"
```

### CI/CD Integration

```yaml
# GitHub Actions example
- name: Import new subscribers
  env:
    BENTO_PUBLISHABLE_KEY: ${{ secrets.BENTO_PUBLISHABLE_KEY }}
    BENTO_SECRET_KEY: ${{ secrets.BENTO_SECRET_KEY }}
    BENTO_SITE_UUID: ${{ secrets.BENTO_SITE_UUID }}
  run: |
    npm install -g @bentonow/bento-cli
    bento subscribers import ./new-subscribers.csv --confirm
```

### Send Transactional Emails

```bash
#!/bin/bash
# Send order confirmation
bento emails send \
  --to "$CUSTOMER_EMAIL" \
  --from "orders@yourcompany.com" \
  --subject "Order Confirmation #$ORDER_ID" \
  --html-body "<h1>Thank you for your order!</h1><p>Order #$ORDER_ID has been confirmed.</p>" \
  --personalizations "{\"order_id\": \"$ORDER_ID\", \"total\": \"$TOTAL\"}"
```

### Build a Sequence from Template Files

```bash
#!/bin/bash
# Add emails to a sequence from a directory of HTML files
SEQUENCE_ID="sequence_abc123"
DELAY=1

for file in ./sequence-emails/*.html; do
  SUBJECT=$(basename "$file" .html | tr '-' ' ')
  bento sequences create-email \
    --sequence-id "$SEQUENCE_ID" \
    --subject "$SUBJECT" \
    --html-file "$file" \
    --delay-interval days \
    --delay-count "$DELAY"
  DELAY=$((DELAY + 1))
done
```

### Multi-Account Profile Switching

```bash
#!/bin/bash
# Run a report across multiple Bento accounts
for profile in staging production; do
  echo "Stats for $profile:"
  bento profile use "$profile"
  bento stats site --json
done
```

### Track Purchase Events

```bash
#!/bin/bash
# Track a purchase from your checkout flow
bento events purchase \
  --email "$CUSTOMER_EMAIL" \
  --amount 4999 \
  --currency USD \
  --key "order_$ORDER_ID" \
  --cart '{"items": [{"product_sku": "SKU123", "product_name": "Pro Plan", "quantity": 1}]}'
```

---


## Environment Variables


Instead of using `bento auth login`, you can set environment variables:

```bash
export BENTO_PUBLISHABLE_KEY="pk_live_..."
export BENTO_SECRET_KEY="sk_live_..."
export BENTO_SITE_UUID="your-site-uuid"
```

Add these to your `~/.zshrc` or `~/.bashrc` for persistence, or use them in CI/CD pipelines.

---


## Troubleshooting


  
    
  
  
    <div className="rounded-lg bg-neutral-800/70 p-4 mt-0 pt-1">
      <h4 className="text-white font-semibold text-lg mb-3">Debug Mode</h4>

      <p className="text-zinc-300 text-sm mb-3">For detailed output, use the verbose flag:</p>

      
        
      

      <p className="text-zinc-300 text-sm mt-4">This shows the full API request and response for debugging.</p>
    </div>
  


---


## Quick Reference


### Auth & Profiles

| Command | Description |
|---------|-------------|
| `bento auth login` | Authenticate with Bento |
| `bento auth status` | Check authentication status |
| `bento auth logout` | Remove stored credentials |
| `bento profile add <name>` | Add a new profile |
| `bento profile list` | List all profiles |
| `bento profile use <name>` | Switch active profile |
| `bento profile remove <name>` | Remove a profile |
| `bento dashboard` | Open Bento dashboard in browser |

### Subscribers

| Command | Description |
|---------|-------------|
| `bento subscribers search --email <email>` | Look up a subscriber |
| `bento subscribers import <file>` | Import from CSV |
| `bento subscribers upsert --email <email>` | Create or update a subscriber |
| `bento subscribers tag --email <email> --add <tags>` | Add/remove tags |
| `bento subscribers field set --email <email> -k <key> -v <value>` | Set a field value |
| `bento subscribers field update --email <email> --fields <json>` | Update fields (triggers automations) |
| `bento subscribers field remove --email <email> -k <key>` | Remove a field |
| `bento subscribers subscribe --email <email>` | Re-subscribe a subscriber |
| `bento subscribers unsubscribe --email <email>` | Unsubscribe a subscriber |
| `bento subscribers change-email --old <email> --new <email>` | Change subscriber email |

### Tags & Fields

| Command | Description |
|---------|-------------|
| `bento tags list [search]` | List tags (optional fuzzy filter) |
| `bento tags create <name>` | Create a new tag |
| `bento tags delete <name>` | Delete a tag |
| `bento fields list [search]` | List custom fields (optional fuzzy filter) |
| `bento fields create <key>` | Create a custom field |

### Events

| Command | Description |
|---------|-------------|
| `bento events track --email <email> --event <name>` | Track an event |
| `bento events purchase --email <email> --amount <cents> --currency <code> --key <id>` | Track a purchase |
| `bento events import <file>` | Bulk import events from JSON |

### Broadcasts & Sequences

| Command | Description |
|---------|-------------|
| `bento broadcasts list` | List broadcasts |
| `bento broadcasts create` | Create a broadcast draft |
| `bento sequences list` | List email sequences |
| `bento sequences create-email --sequence-id <id>` | Create email in a sequence |
| `bento sequences update-email --template-id <id>` | Update a sequence email |

### Emails, Templates & Forms

| Command | Description |
|---------|-------------|
| `bento emails send --to <email> --from <email> --subject <text> --html-body <html>` | Send transactional email |
| `bento emails send-batch --file <json>` | Batch send transactional emails |
| `bento templates get <id>` | Get an email template |
| `bento templates update <id>` | Update an email template |
| `bento forms responses <form-id>` | Get form responses |

### Workflows, Stats & Dashboard

| Command | Description |
|---------|-------------|
| `bento workflows list` | List workflows |
| `bento stats site` | View site statistics |
| `bento stats segment <segment-id>` | View segment statistics |
| `bento stats report <report-id>` | View report statistics |

### Skills & Experimental

| Command | Description |
|---------|-------------|
| `bento skills list` | List available skills |
| `bento skills install [skill-name]` | Install skills to AI agents |
| `bento experimental validate-email <email>` | Validate an email address |
| `bento experimental guess-gender <name>` | Guess gender from name |
| `bento experimental geolocate <ip>` | Geolocate an IP address |
| `bento experimental blacklist --domain <domain>` | Check blacklist status |
| `bento experimental moderate <content>` | Content moderation |

### Global Flags

| Flag | Description |
|------|-------------|
| `--json` | Output in JSON format |
| `--quiet` | Suppress non-error output |
| `--verbose` | Show detailed debug info |
| `--dry-run` | Preview without making changes |
| `--confirm` | Skip confirmation prompts |
| `--limit <n>` | Process only first N items |
| `--sample <n>` | Show N sample items in preview |

---


## Get Help


- **GitHub Repository**: [github.com/bentonow/bento-cli](https://github.com/bentonow/bento-cli)
- **Issues & Feature Requests**: [github.com/bentonow/bento-cli/issues](https://github.com/bentonow/bento-cli/issues)
- **Discord**: [Join the community](https://discord.gg/ssXXFRmt5F)
- **Email Support**: support@bentonow.com

---


## Related


- [Bento MCP Server](/docs/integrations/mcp) - AI-powered email marketing with Claude, Cursor, and more
- [Node.js SDK](/docs/examples/nodejs) - Integrate Bento into your Node.js applications
- [API Reference](/docs/developer_guides/introduction) - Full API documentation
- [Bento Skills](/docs/integrations/skills) - Install CLI skills into AI agent harnesses