npm package: @reddgrow/cli
Description: AI Agent Reddit Toolkit — safe Reddit intelligence via ReddGrow API
Latest version: 0.1.6

<p align="center">
  <img src="https://reddgrow.ai/image/cli-banner.png" alt="ReddGrow CLI" width="700">
</p>

<p align="center">
  <b>Reddit Intelligence for AI Agents</b>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@reddgrow/cli"><img src="https://img.shields.io/npm/v/%40reddgrow%2Fcli?style=flat-square&color=FF4500&label=npm" alt="npm version"></a>
  <a href="https://github.com/reddgrow/reddgrow-mono/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="license MIT"></a>
</p>

<br>

---

## What is ReddGrow?

68% of AI-generated answers cite Reddit. ReddGrow is a Reddit intelligence platform that finds the conversations that matter — and the CLI gives AI agents direct access to that data.

Search subreddits, read posts and comments, analyze user profiles, track domain mentions, and check posting rules — all through a clean JSON API designed for agent workflows.

→ [reddgrow.ai](https://reddgrow.ai)

---

## Get Your API Key

1. Sign up at [reddgrow.ai](https://reddgrow.ai)
2. Go to **Settings → API Keys**
3. Create a new key — it starts with `rg_`
4. Use it with the CLI or set the environment variable:

```bash
reddgrow auth login rg_your_api_key_here
# or
export REDDGROW_API_KEY=rg_your_api_key_here
```

---

## Install

![npm](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white&style=flat-square)

```bash
npm install -g @reddgrow/cli
```

![yarn](https://img.shields.io/badge/yarn-2C8EBB?logo=yarn&logoColor=white&style=flat-square)

```bash
yarn global add @reddgrow/cli
```

![pnpm](https://img.shields.io/badge/pnpm-F69220?logo=pnpm&logoColor=white&style=flat-square)

```bash
pnpm add -g @reddgrow/cli
```

![bun](https://img.shields.io/badge/bun-black?logo=bun&logoColor=white&style=flat-square)

```bash
bun add -g @reddgrow/cli
```

---

## Quick Start

```bash
# 1. Install globally
npm install -g @reddgrow/cli
```

```bash
# 2. Authenticate
reddgrow auth login rg_your_api_key_here
```

```bash
# 3. Fetch trending posts from any subreddit
reddgrow subreddits posts typescript --sort top --time week
```

---

## Commands

### Auth

| Command | Description |
|---------|-------------|
| `reddgrow auth login <key>` | Save your API key |
| `reddgrow auth whoami` | Show identity and credit balance |
| `reddgrow auth status` | Show connection status |
| `reddgrow auth logout` | Remove saved API key |

### Subreddits (`r`)

| Command | Description |
|---------|-------------|
| `reddgrow subreddits search <query>` | Find relevant communities |
| `reddgrow subreddits about <name>` | Get community info and stats |
| `reddgrow subreddits rules <name>` | Get posting rules |
| `reddgrow subreddits posts <name>` | Fetch the post feed |
| `reddgrow subreddits comments <name>` | Get recent comment stream |
| `reddgrow subreddits wiki <name>` | List wiki pages |
| `reddgrow subreddits wiki-page <name> <page>` | Read a wiki page |
| `reddgrow subreddits widgets <name>` | Get sidebar widgets |
| `reddgrow subreddits traffic <name>` | Get traffic statistics |
| `reddgrow subreddits check-url <name> <url>` | Check if URL was already posted |

**Options for `subreddits posts`:** `--sort hot\|new\|top\|rising\|controversial` · `--time hour\|day\|week\|month\|year\|all` · `--limit <n>`

### Posts

| Command | Description |
|---------|-------------|
| `reddgrow posts search <query>` | Search posts across all of Reddit |
| `reddgrow posts comments <subreddit> <id>` | Get comments for a post |
| `reddgrow posts duplicates <subreddit> <id>` | Find duplicate submissions |
| `reddgrow posts batch <id> [id...]` | Fetch multiple posts at once |

### Users (`u`)

| Command | Description |
|---------|-------------|
| `reddgrow users profile <username>` | Get user profile and karma |
| `reddgrow users posts <username>` | Get post history |
| `reddgrow users comments <username>` | Get comment history |

### Domains (`d`)

| Command | Description |
|---------|-------------|
| `reddgrow domains mentions <domain>` | Find Reddit posts linking to a domain |

---

## Output Modes

ReddGrow auto-detects whether it's running interactively or piped, and adjusts output accordingly.

**Human mode** (interactive terminal) — rich, colored output:

```
  ┌─────────────────────────────────────────┐
  │  ✓ Connected to ReddGrow API            │
  │                                         │
  │  API Key    rg_abc6...ef12              │
  │  API URL    https://api.reddgrow.ai     │
  └─────────────────────────────────────────┘
```

**Agent mode** (piped / non-TTY) — raw JSON to stdout, errors to stderr:

```json
{
  "id": "typescript",
  "subscribers": 312000,
  "title": "TypeScript",
  "description": "TypeScript is a language for application-scale JavaScript."
}
```

> [!TIP]
> Mode is auto-detected when piping output. Force it explicitly with `--mode agent` or `export REDDGROW_MODE=agent`.

---

## AI Agent Integration

ReddGrow ships a `SKILL.md` that Claude and other AI agents can consume via [OpenClaw](https://openclaw.dev).

**Claude / OpenClaw:** The `SKILL.md` bundled in this package teaches your agent all commands, workflows, and credit costs automatically.

**Pipe to jq:**

```bash
# Get the top 5 post titles from r/typescript this week
reddgrow subreddits posts typescript --sort top --time week | jq '.[0:5] | .[].title'

# Save subreddit info to a file
reddgrow subreddits about typescript > typescript-info.json

# Check if a URL has been shared before posting
reddgrow subreddits check-url typescript "https://mysite.com/article" | jq '.alreadyPosted'
```

**Recommended workflow for agents:**

```bash
# 1. Research the community
reddgrow subreddits about <name>
reddgrow subreddits rules <name>
reddgrow subreddits wiki <name>

# 2. Check for duplicates before posting
reddgrow subreddits check-url <name> "<url>"

# 3. Monitor your account
reddgrow auth whoami
```

---

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| `REDDGROW_API_KEY` | Your API key (overrides saved key) | — |
| `REDDGROW_API_URL` | API base URL | `https://api.reddgrow.ai` |
| `REDDGROW_MODE` | Output mode: `human` or `agent` | auto-detected |

Config is stored at `~/.reddgrow/config.json`. The `--mode` flag and environment variables always take precedence over the saved config.

---

## Links

- **Website:** [reddgrow.ai](https://reddgrow.ai)
- **npm:** [@reddgrow/cli](https://www.npmjs.com/package/@reddgrow/cli)

---

## License

MIT © [ReddGrow](https://reddgrow.ai)