@coloop-ai/reddit-ads-cli

Command-line interface for the Reddit Ads API v3. Every operation in the API is a command: path parameters are positional, query parameters are flags, request bodies are passed with --data, and responses are printed as JSON. The command tree is generated from Reddit's OpenAPI document, so it stays complete as the API grows.

This package is maintained by CoLoop. It is not an official Reddit tool. It requires Node.js 20.12 or newer.

Install

npm install -g @coloop-ai/reddit-ads-cli

Or run it without installing:

npx @coloop-ai/reddit-ads-cli --help

Set up

Run the login command. On first use it explains how to create a Reddit developer application, asks for its app ID and secret, opens a browser for you to authorise the CLI, and then lists the ad accounts you can access so one can become the default:

reddit-ads auth login

What you need before that:

1. A developer application, created in Reddit Ads Manager under Business > Developer Portal (business admins only). Reddit's guide: Create a Developer Application.
2. Its redirect URL set to http://localhost:47100/callback. Any other URL works with --redirect-uri, and --manual lets you paste the redirect back when no browser is available on the machine.

For scripts and CI, skip the prompts by passing --client-id and --client-secret, or by setting REDDIT_ADS_CLIENT_ID and REDDIT_ADS_CLIENT_SECRET (a .env file in the working directory is loaded automatically). The app ID and secret are remembered with the profile, so later logins need nothing.

Tokens live in ~/.config/reddit-ads-cli/credentials.json (mode 0600), or under $XDG_CONFIG_HOME or $REDDIT_ADS_CONFIG_DIR when set. Access tokens are refreshed automatically. reddit-ads auth status shows what is stored without printing secrets, reddit-ads auth token prints a valid access token for use with other tools, and reddit-ads auth logout removes it.

Usage

reddit-ads me
reddit-ads businesses list-mine
reddit-ads ad-accounts list-by-business <business_id>
reddit-ads campaigns list --all
reddit-ads campaigns get <campaign_id>
reddit-ads schema campaigns create --example > campaign.json
reddit-ads campaigns create --data @campaign.json --dry-run
reddit-ads ads list --campaign-id <campaign_id> --page-size 100
reddit-ads reports get --data '{"data":{"starts_at":"2026-08-01T00:00:00Z","ends_at":"2026-08-08T00:00:00Z","fields":["SPEND","IMPRESSIONS"],"breakdowns":["DATE","CAMPAIGN_ID"]}}' --all
reddit-ads targeting search-communities --query running

Commands that work within one ad account, such as campaigns list, take the ad account ID as their first argument. It can be omitted when REDDIT_ADS_AD_ACCOUNT_ID is set or the profile has a default, which auth login offers to pick and reddit-ads config set ad-account <id> changes.

Groups with a single command run it directly, so reddit-ads me is reddit-ads me get. Every command documents its operation, docs page, required scopes and rate-limit policy in --help:

reddit-ads campaigns list --help

Conventions

• Path parameters are positional, in the order they appear in the API path. The ad account ID is optional when a default is configured.
• Query parameters are kebab-case flags: page.size becomes --page-size, configured_status becomes --configured-status. Array parameters accept repeated flags or comma-separated values.
• Request bodies are passed with --data, as inline JSON, @path to read a file, or - to read standard input. reddit-ads schema <group> <command> prints the body and response schemas with every reference inlined, and --example prints a starter body built from Reddit's documented examples.
• Paginated commands accept --all, which follows page.token pagination and merges every page into one document: the data arrays are concatenated, and for reports the data.metrics rows are.
• Output is JSON on stdout: pretty-printed on a terminal, compact otherwise. --compact forces one line and --format jsonl prints one line per item of data.
• Errors go to stderr with the HTTP status, the API's message and field errors, and the exit code is 1.

Flags on every API command

Discovering request bodies

reddit-ads schema campaigns create            # request body schema, starter body, response schemas
reddit-ads schema campaigns create --example  # only the starter body
reddit-ads schema reports get --body          # only the request body schema

The output comes from Reddit's OpenAPI document bundled with the CLI, so it works offline and matches the commands exactly.

The api escape hatch

Any path under the API base URL can be called directly:

reddit-ads api GET /me
reddit-ads api GET /ad_accounts/<ad_account_id>/campaigns --query page.size=10 --all
reddit-ads api POST /ad_accounts/<ad_account_id>/reports --data @report.json

Environment variables

REDDIT_ADS_ACCESS_TOKEN and REDDIT_ADS_REFRESH_TOKEN suit CI and other non-interactive environments.

Commands

Rate limits and retries

Reddit applies per-endpoint-group rate limits and returns RateLimit headers. On HTTP 429 the CLI waits for the reset time advertised in those headers (or backs off exponentially) and retries up to --retries times. Requests send a Reddit-style user agent that includes the authorizing Reddit username.

Development

pnpm install
pnpm run cli -- --help   # Run from source
pnpm run check           # Schema check, typecheck, lint, format, tests with coverage, build

See MAINTAINERS.md for the schema regeneration and release workflow. New dependency versions must wait seven days before pnpm can install them; this is configured in pnpm-workspace.yaml as a supply-chain safety delay.

License

MIT License. See LICENSE.