Reddit Ads CLI Skill

You have access to reddit-ads-cli, a read-only CLI for the Reddit Ads API (v3). Use it to query ad accounts, list campaigns and ads, generate performance reports, inspect creatives, manage custom audiences, track conversion pixels, and explore targeting options (subreddits, interests, geos).

Quick start

# Check if the CLI is available
reddit-ads-cli --help

# List accessible ad accounts
reddit-ads-cli accounts

# List campaigns for an account
reddit-ads-cli campaigns t2_abc123

If the CLI is not installed, install it:

npm install -g reddit-ads-cli

Authentication

The CLI requires a Reddit OAuth access token. Credentials are resolved in this order:

1. --credentials <path> flag (per-command)
2. Environment variable: REDDIT_ADS_ACCESS_TOKEN
3. Auto-detected file: ~/.config/reddit-ads-cli/credentials.json

The credentials file format:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "username": "your_reddit_username"
}

Only access_token is required. The username field is used to build the User-Agent string (cli:reddit-ads-cli:v<version> (by /u/<username>)). Reddit rate-limits requests without a proper User-Agent.

When using environment variables:

• REDDIT_ADS_ACCESS_TOKEN -- required
• REDDIT_ADS_CLIENT_ID -- optional
• REDDIT_ADS_CLIENT_SECRET -- optional
• REDDIT_ADS_USERNAME -- optional, for User-Agent

Before running any command, verify credentials are configured by running reddit-ads-cli accounts. If it fails with a credentials error, ask the user to set up authentication.

Entity hierarchy

Ad Account (t2_XXXXX)
 +-- Campaign
 |    +-- Ad Group
 |         +-- Ad
 +-- Creative
 +-- Custom Audience
 +-- Pixel
      +-- Pixel Events

Ad account IDs use the t2_ prefix (e.g., t2_abc123).

Output format

All commands output pretty-printed JSON by default. Use --format compact for single-line JSON (useful for piping).

Commands reference

Account discovery

# List all ad accounts accessible by the authenticated user
reddit-ads-cli accounts

# Get details of a specific ad account
reddit-ads-cli account t2_abc123

Campaign hierarchy

# List campaigns (optionally filter by status)
reddit-ads-cli campaigns t2_abc123
reddit-ads-cli campaigns t2_abc123 --status ACTIVE

# List ad groups (optionally filter by campaign or status)
reddit-ads-cli adgroups t2_abc123
reddit-ads-cli adgroups t2_abc123 --campaign-id campaign_abc
reddit-ads-cli adgroups t2_abc123 --status PAUSED

# List ads (optionally filter by ad group, campaign, or status)
reddit-ads-cli ads t2_abc123
reddit-ads-cli ads t2_abc123 --ad-group-id adgroup_abc
reddit-ads-cli ads t2_abc123 --campaign-id campaign_abc
reddit-ads-cli ads t2_abc123 --status ACTIVE

campaigns options

• --status <status> -- filter by status (ACTIVE, PAUSED, etc.)

adgroups options