CLI Reference

@reddgrow/cli is the official command-line interface for the ReddGrow API. It supports both interactive human-readable output and raw JSON for scripting and AI agent pipelines.

Installation

# npm
npm install -g @reddgrow/cli

# yarn
yarn global add @reddgrow/cli

# pnpm
pnpm add -g @reddgrow/cli

# bun
bun add -g @reddgrow/cli

Verify the install:

reddgrow --version

Quick Start

1. Save your API key

reddgrow auth login rg_your_key_here

2. Verify the connection

reddgrow auth whoami

3. Make your first data request

reddgrow reddit subreddits posts MachineLearning --sort top --time week

Command Groups

Reddit reads (subreddits, posts, users, domains) live under reddgrow reddit, for example reddgrow reddit posts search "ai agents". reddgrow reddit job <id> checks an async job (see below).

Async jobs

Reddit reads are async jobs on the API side: a call returns 202 Accepted with a jobId, and the result is fetched from a jobs endpoint. The CLI hides this. reddgrow reddit ... commands wait for the job (polling every 3 seconds, giving up after 15 minutes) and print the same result as before. Most jobs finish in under a minute, and it can take a few minutes when the scraper is busy.

To skip waiting, add --no-wait. The CLI prints the jobId and exits, and you check on it later with reddgrow reddit job <id>, which is free:

# Create the job and return immediately
reddgrow reddit subreddits posts typescript --sort new --no-wait
# jobId: job_01HXYZ...

# Check status, or fetch the result once it is completed
reddgrow reddit job job_01HXYZ...

The same flow over HTTP:

# 1. Create the job (credits are reserved here)
curl -H "x-api-key: $REDDGROW_API_KEY" \
  "https://api.reddgrow.ai/v1/reddit/subreddits/typescript/posts?sort=new"
# {"jobId":"job_01HXYZ...","status":"queued"}

# 2. Poll until status is completed or failed (0 credits)
curl -H "x-api-key: $REDDGROW_API_KEY" \
  "https://api.reddgrow.ai/v1/reddit/jobs/job_01HXYZ..."

status is queued, running, completed (with result) or failed (with error). Jobs and results are kept for 24 hours. Reads are priced per Reddit page fetched: creating a job reserves the credits for the pages your --limit can need, and unused pages are refunded when it finishes. The finished job reports the final charge as creditsCharged, and the CLI shows that final amount. A job that fails because ReddGrow's scraper was unavailable (503) refunds its full reservation.

Global Options

Further Reading

• Auth — Login, logout, and connection status
• Subreddits: Post feeds and comment streams
• Posts: Post search and post comments
• Users: User post and comment history
• Domains — Domain mention tracking
• Output Modes — Human vs agent mode
• Configuration — Environment variables and config file