Reddit Ads CLI

Reddit Ads data analysis and reporting via reddit-ads-cli. Use when the user wants to check Reddit ad performance, list campaigns/ad groups/ads, explore subr...

Security Scan

The skill's instructions are coherent with a Reddit Ads CLI, but the registry metadata does not declare the credentials and env vars the skill actually requires and it recommends installing an npm package of unknown origin — these mismatches are worrying.

Purpose & Capability

The SKILL.md describes a Reddit Ads CLI and legitimately requires a Reddit OAuth access token and (optionally) client_id/client_secret/username. However, the registry metadata lists no required environment variables or primary credential. That mismatch (declaring no credentials while the runtime docs require secrets) is incoherent and should be fixed by the publisher.

Instruction Scope

Runtime instructions are focused on calling reddit-ads-cli commands and on how to supply credentials (flag, env var, or ~/.config/reddit-ads-cli/credentials.json). The instructions do not attempt to read unrelated system files, but they do reference a specific config path and several environment variables that are not reflected in the skill metadata — the agent could read local credential files or environment variables if available, which is expected for this class of tool but must be declared.

Install Mechanism

There is no automated install spec in the registry (instruction-only), but SKILL.md tells users to run `npm install -g reddit-ads-cli`. Installing a global npm package is a moderate-risk action because the package source and ownership are not provided; the skill itself will not perform the install automatically, but the guidance suggests installing an external package the user should vet.

Credentials

The credentials and env vars named in SKILL.md (REDDIT_ADS_ACCESS_TOKEN, REDDIT_ADS_CLIENT_ID, REDDIT_ADS_CLIENT_SECRET, REDDIT_ADS_USERNAME and a credentials file path) are proportionate to the advertised functionality. However, the registry metadata lists none of these as required and gives no primary credential — this omission creates opacity about what secrets the skill will expect or access.

Persistence & Privilege

The skill is instruction-only (no code files, no install performed by the registry) and does not request always:true or other elevated persistent privileges. It does not modify other skills or system-wide settings per the provided content.

What to consider before installing

This skill appears to be a straightforward wrapper around a reddit-ads-cli npm tool, but the published metadata omits the credentials the runtime actually needs. Before installing or using it: - Verify the npm package: check npmjs.org (or the package homepage/repository) and the publisher/maintainer identity; prefer well-known sources. - Do not reuse high-privilege tokens. Create a read-only OAuth token with the minimum scope needed for reporting and revoke it after use if possible. - Store credentials in a dedicated, access-controlled location and avoid exposing them in shared shells. If you must use the ~/.config credentials file, inspect its contents and permissions. - Ask the skill publisher to update the registry metadata to declare the required env vars and primary credential so the required permissions are explicit. - If you're concerned about running global npm packages, run the CLI in an isolated environment (container or VM) or inspect the package source before installing. These steps will reduce risk and clarify whether the skill is appropriate for your environment.

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

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

ads options

• --ad-group-id <id> -- filter by ad group ID
• --campaign-id <id> -- filter by campaign ID
• --status <status> -- filter by status (ACTIVE, PAUSED, etc.)

Performance reports

The report command generates performance reports via a POST request. Both --start-date and --end-date are required.

# Campaign-level report (default level)
reddit-ads-cli report t2_abc123 \
  --start-date 2026-03-01 \
  --end-date 2026-03-15 \
  --metrics impressions,clicks,spend,ecpm,ctr

# Ad group level with timezone
reddit-ads-cli report t2_abc123 \
  --start-date 2026-03-01 \
  --end-date 2026-03-15 \
  --level AD_GROUP \
  --metrics impressions,clicks,spend \
  --campaign-id campaign_abc \
  --timezone America/New_York

# Account-level report
reddit-ads-cli report t2_abc123 \
  --start-date 2026-03-01 \
  --end-date 2026-03-15 \
  --level ACCOUNT

# Ad-level report filtered to a specific ad group
reddit-ads-cli report t2_abc123 \
  --start-date 2026-03-01 \
  --end-date 2026-03-15 \
  --level AD \
  --ad-group-id adgroup_abc

report options

• --start-date <date> -- start date, YYYY-MM-DD (required)
• --end-date <date> -- end date, YYYY-MM-DD (required)
• --level <level> -- report level: ACCOUNT, CAMPAIGN, AD_GROUP, AD (default: CAMPAIGN)
• --metrics <metrics> -- comma-separated metrics (default: impressions,clicks,spend). Other metrics shown in examples: ecpm, ctr. The CLI passes metric names directly to the Reddit Ads API without validation. Refer to the Reddit Ads API docs for all available metrics.
• --campaign-id <id> -- filter by campaign ID
• --ad-group-id <id> -- filter by ad group ID
• --timezone <tz> -- timezone (e.g., America/New_York)

Creatives

# List ad creatives for an account (supports pagination)
reddit-ads-cli creatives t2_abc123
reddit-ads-cli creatives t2_abc123 --limit 50 --offset 10

# Get a specific creative
reddit-ads-cli creative t2_abc123 creative_xyz

creatives options

• --limit <n> -- results per page (default: 25)
• --offset <n> -- start index (default: 0)

Custom audiences

# List custom audiences (supports pagination)
reddit-ads-cli custom-audiences t2_abc123
reddit-ads-cli custom-audiences t2_abc123 --limit 50 --offset 10

custom-audiences options

• --limit <n> -- results per page (default: 25)
• --offset <n> -- start index (default: 0)

Pixels & conversion tracking

# List conversion pixels for an account
reddit-ads-cli pixels t2_abc123

# List events for a specific pixel
reddit-ads-cli pixel-events t2_abc123 pixel_xyz

Targeting options

# Search subreddits available for targeting (--query is required)
reddit-ads-cli subreddits --query gaming
reddit-ads-cli subreddits --query technology --limit 50

# List interest targeting categories
reddit-ads-cli interests

# List geographic targeting options (optionally search)
reddit-ads-cli geos
reddit-ads-cli geos --query "United States"

subreddits options

• --query <q> -- search query (required)
• --limit <n> -- results per page (default: 25)

geos options

• --query <q> -- search query (optional)

Pagination summary

Commands that support pagination via --limit and --offset: creatives, custom-audiences, subreddits.

Commands without pagination options: accounts, account, campaigns, adgroups, ads, pixels, pixel-events, interests, geos.

Workflow guidance

When the user asks for a quick overview

1. Run reddit-ads-cli accounts to find accessible accounts
2. Run reddit-ads-cli campaigns <account-id> to list campaigns
3. Use reddit-ads-cli report <account-id> --start-date ... --end-date ... for a performance snapshot

When the user asks for deep analysis

1. Start with an account-level report (--level ACCOUNT) to see overall performance
2. Drill down to --level CAMPAIGN to identify top/bottom campaigns
3. Further drill down with --level AD_GROUP or --level AD for underperforming campaigns
4. Filter by --campaign-id or --ad-group-id to focus on specific entities
5. Cross-reference with creatives to review ad content

When the user asks about creative performance

1. Run report with --level AD to get ad-level metrics
2. Use ads to find the ad details
3. Use creatives and creative to inspect the actual creative content

When the user asks about targeting options

1. Use subreddits --query <topic> to discover targetable subreddits
2. Use interests to see available interest categories
3. Use geos to explore geographic targeting options

When the user asks about conversion tracking

1. Run pixels to list active conversion pixels
2. Use pixel-events with a pixel ID to check what events are being tracked
3. Use report with conversion-related metrics to see performance

When the user asks about audiences

1. Use custom-audiences to list existing custom audiences
2. Paginate through results using --limit and --offset

Error handling

• Authentication errors -- ask the user to verify their access token; check that ~/.config/reddit-ads-cli/credentials.json exists and contains a valid access_token
• Credentials not found -- the CLI looks for credentials in three places (flag, env var, default file); ensure at least one is configured
• Empty reports -- check date range, entity status, and whether the account had active ads in the period
• Rate limiting -- Reddit rate-limits requests without a proper User-Agent; ensure username is set in credentials
• Unknown command -- run reddit-ads-cli --help to see available commands

API documentation references

• reddit-ads-cli documentation
• Reddit Ads API v3 docs
• Reddit OAuth2 authentication