mads — Meta Ads CLI

Command-line interface for Meta (Facebook) Ads API. Manage ad performance, create and control ads, and run automated kill/scale checks using a sliding threshold engine.

Built for performance marketers who live in the terminal.

Features

• Ad management — list, create, pause, unpause ads from the command line
• Performance reporting — account, campaign, ad set, and ad-level metrics
• Sliding glide kill checks — automated CPA-based kill/scale decisions that tighten weekly
• A/B evaluation — compare variant vs control with both relative and absolute thresholds
• Targeting inspection — see full geo, age, interest targeting for any ad set
• Image uploads — upload creatives and get image hashes
• JSON output — pipe everything into jq, scripts, or other tools

Installation

# Clone
git clone https://github.com/insightslab-ai/mads.git
cd mads

# Make executable and symlink
chmod +x mads
ln -sf "$(pwd)/mads" ~/bin/mads

# Configure
mkdir -p ~/.config/mads
cp config.example.env ~/.config/mads/config.env
# Edit config.env with your Meta API credentials

Requirements

• Python 3.8+
• curl (used for API calls)
• A Meta Ads access token (create one here)

Quick Start

# Set your credentials
export META_ACCESS_TOKEN=your_token
export META_AD_ACCOUNT_ID=act_123456789

# List active ads
mads ads

# 7-day account performance
mads performance --days 7

# Check which ads should be killed or scaled
mads kill-check --days 7 --dry-run

Commands

mads ads

List ads in the account.

mads ads                          # active ads (default)
mads ads --status paused          # paused ads
mads ads --status all             # all ads
mads ads --json                   # JSON output

mads performance

Account-level or ad-level performance report.

mads performance --days 7                    # account summary
mads performance --ad-id 12345 --days 3      # specific ad
mads performance --adset-id 12345 --days 14  # ad set level
mads performance --json                      # JSON output

mads campaigns

List campaigns with status and budget.

mads adsets

List ad sets with status, budget, and targeting summary.

mads create-ad

Create a new ad. Requires META_PAGE_ID to be set.

mads create-ad \
  --adset-id 12345 \
  --name "My New Ad" \
  --headline "Your Headline Here" \
  --body "Ad body text" \
  --image-hash abc123 \
  --link "https://example.com" \
  --cta SIGN_UP

mads pause / mads unpause

Pause or unpause an ad.

mads pause 12345 --confirm        # pause (requires --confirm)
mads unpause 12345 --confirm      # reactivate

mads upload-image

Upload a creative image and get the image hash.

mads upload-image ./my-creative.png
# Returns: Image hash: abc123def456

mads targeting

Inspect full targeting for an ad set.

mads targeting 12345
# Shows: geo, age, gender, interests, exclusions, placements

mads kill-check

The core feature. Evaluates all active ads against the sliding glide thresholds and recommends kill/scale actions.

mads kill-check --days 7 --dry-run    # see what WOULD happen
mads kill-check --days 7              # actually pause ads above kill line
mads kill-check --json                # structured output for scripts

mads evaluate

Compare a variant ad against a control using both relative and absolute thresholds.

mads evaluate <variant_id> <control_id> --days 2
mads evaluate <variant_id> <control_id> --json

Outcomes: promote, promote_control_dead, kill_absolute, discard, insufficient_data

mads thresholds

Show the current week's threshold schedule.

mads thresholds
mads thresholds --json

Sliding Glide Threshold System

Most ad management tools use a static CPA kill line. mads uses a sliding glide — thresholds tighten automatically each week, forcing continuous improvement.

How it works

1. You set a baseline CPA (your current blended CPA) and an anchor date
2. Each week, the kill line drops by a configurable percentage (default: 10%)
3. The glide has a floor — it never drops below your minimum viable CPA
4. Ads above the kill line get paused. Ads well below it get flagged for scaling.

Example

Baseline CPA: $3.50 (anchored March 1)
Weekly drop: 10%
Floor: $2.00

Week 0: Kill > $3.50
Week 1: Kill > $3.15
Week 2: Kill > $2.84
Week 3: Kill > $2.55
Week 4: Kill > $2.30
Week 5: Kill > $2.07
Week 6+: Kill > $2.00 (floor)

Verdict bands

Verdict	Meaning
🔴 KILL	CPA above kill line — pause immediately
🟡 ITERATE	CPA between 80-100% of kill — test copy/creative changes
🟢 HOLD	CPA between 68-80% of kill — leave running
🚀 SCALE	CPA below 68% of kill + CTR ≥ 1% + 5+ leads — increase budget
⚪ INSUFFICIENT	Not enough data (< $25 spend or < 1500 impressions)

Configuration

Set these in ~/.config/mads/config.env:

MADS_GLIDE_BASELINE_CPA=3.50     # your starting blended CPA
MADS_GLIDE_ANCHOR=2024-01-15     # date you set the baseline
MADS_GLIDE_FLOOR=2.00            # never kill below this CPA
MADS_GLIDE_WEEKLY_DROP=0.10      # 10% drop per week (default)

Configuration

mads reads configuration from environment variables. The bash wrapper sources ~/.config/mads/config.env automatically.

Variable	Required	Description
META_ACCESS_TOKEN	Yes	Meta API access token
META_AD_ACCOUNT_ID	Yes	Ad account ID (e.g., act_123456789)
META_PAGE_ID	For create-ad	Facebook Page ID
META_API_VERSION	No	API version (default: v21.0)
MADS_GLIDE_BASELINE_CPA	For kill-check	Starting CPA baseline
MADS_GLIDE_ANCHOR	For kill-check	Baseline date (YYYY-MM-DD)
MADS_GLIDE_FLOOR	For kill-check	Minimum CPA threshold
MADS_GLIDE_WEEKLY_DROP	No	Weekly drop rate (default: 0.10)

License

MIT — see LICENSE.

Built by Insights Lab