rdt-cli 0.2.0

A CLI for Reddit — browse feeds, read posts, search, and interact via terminal 📖

rdt-cli

A CLI for Reddit — browse feeds, read posts, search, and interact via reverse-engineered API 📖

English | 中文

More Tools

• xiaohongshu-cli — Xiaohongshu CLI for search, reading, and posting
• twitter-cli — Twitter/X CLI for timelines, bookmarks, and posting
• bilibili-cli — Bilibili CLI for videos, users, search, and feeds
• discord-cli — Discord CLI for local-first sync, search, and export
• tg-cli — Telegram CLI for local-first sync, search, and export

Features

• 🔐 Auth — auto-extract browser cookies, status check, whoami
• 🏠 Feed — browse home feed, popular, and /r/all
• 📋 Subreddits — browse any subreddit with sort/time filters, view subreddit info
• 📰 Posts — read posts and comment trees with syntax highlighting
• 🔢 Short-index navigation — rdt show 3 to read, rdt open 3 to browser
• 🔍 Search — full-text search with subreddit, sort, and time filters
• 📤 Export — export search results to CSV or JSON; -o file.json on any listing
• 👤 Users — view user profiles and post history
• ⬆️ Interactions — upvote/downvote, save/unsave, subscribe/unsubscribe, comment (with 1.5-4s rate-limit delay)
• 🛡️ Anti-detection — consistent Chrome 133 fingerprint, sec-ch-ua alignment, Gaussian jitter, exponential backoff
• 📊 Structured output — --yaml, --json, --output FILE, --compact, --full-text
• 📦 Stable envelope — see SCHEMA.md for ok/schema_version/data/error
• 🤖 Agent-friendly — Rich output on stderr, --compact for token-efficient output

AI Agent Tip: Prefer --yaml for structured output unless strict JSON is required. Non-TTY stdout defaults to YAML automatically. Use --compact to reduce token usage.

Installation

# Recommended: uv tool (fast, isolated)
uv tool install rdt-cli

# Or: pipx
pipx install rdt-cli

Upgrade to the latest version:

uv tool upgrade rdt-cli
# Or: pipx upgrade rdt-cli

From source:

git clone [e-mail]:jackwener/rdt-cli.git
cd rdt-cli
uv sync

Usage

# ─── Auth ─────────────────────────────────────────
rdt login                             # Extract cookies from browser
rdt status                            # Check login status
rdt status --json                     # Structured JSON envelope
rdt whoami                            # Detailed profile (karma, account age)
rdt logout                            # Clear saved cookies

# ─── Browse ───────────────────────────────────────
rdt feed                              # Home feed (requires login)
rdt popular                           # Popular posts
rdt popular --full-text               # Show full titles
rdt all                               # /r/all
rdt sub python                        # Browse subreddit
rdt sub programming -s top -t week    # Sort + time filter
rdt sub-info python                   # Subreddit info (subscribers, etc.)
rdt user spez                         # User profile
rdt user-posts spez                   # User's submitted posts

# Short index works after list commands (feed/popular/sub/search)
rdt sub python
rdt show 1                            # Read post #1 from listing
rdt open 1                            # Open post #1 in browser
rdt upvote 1                          # Upvote post #1

# ─── Reading ──────────────────────────────────────
rdt read 1abc123                      # Read post by ID
rdt show 3                            # Read result #3 from last listing
rdt show 1 -s top                     # Sort comments by top
rdt open 3                            # Open in browser

# ─── Search ───────────────────────────────────────
rdt search "python async"             # Global search
rdt search "rust vs go" -r programming  # Within subreddit
rdt search "ML" -s top -t year        # Sort by top, last year
rdt search "AI" -o results.json       # Save to file
rdt search "rust" --compact --json    # Compact agent output

# ─── Export ───────────────────────────────────────
rdt export "python tips" -n 100 -o tips.csv
rdt export "rust" --format json -o results.json

# ─── Interactions (require login) ─────────────────
rdt upvote 3                          # Upvote result #3
rdt upvote 3 --down                   # Downvote
rdt upvote 3 --undo                   # Remove vote
rdt save 3                            # Save result #3
rdt save 3 --undo                     # Unsave
rdt subscribe python                  # Subscribe to r/python
rdt subscribe python --undo           # Unsubscribe
rdt comment 3 "Great post!"           # Comment on result #3

Authentication

rdt-cli supports browser cookie extraction to authenticate with Reddit:

1. Saved cookies — loads from ~/.config/rdt-cli/credential.json
2. Browser cookies — auto-detects installed browsers and extracts cookies (supports Chrome, Firefox, Edge, Brave)

rdt login automatically tries all installed browsers and uses the first one with valid cookies.

Cookie TTL

Saved cookies are valid for 7 days by default. After that, the client automatically attempts to refresh from the browser. If browser extraction fails, the existing cookies are used with a warning.

Short-Index Navigation

After any listing command such as feed, popular, all, sub, or search, the CLI stores the latest ordered post list in ~/.config/rdt-cli/index_cache.json.

• rdt show <N> reads the Nth post from the latest listing
• rdt open <N> opens the Nth post in the browser
• rdt upvote <N>, rdt save <N>, rdt comment <N> reuse the same short index
• Empty listings clear the index cache, so old results are not reused by accident

Environment Variables

Variable	Default	Description
OUTPUT	auto	Output format: json, yaml, rich, or auto (→ YAML when non-TTY)

Rate Limiting & Anti-Detection

rdt-cli includes anti-detection measures designed to minimize risk:

Request Timing

• Gaussian jitter: Delays between requests use a truncated Gaussian distribution (~1s mean, σ=0.3)
• Random long pauses: ~5% of requests include an additional 2-5 second delay simulating reading behavior
• Auto-retry: Exponential backoff on HTTP 429/5xx and network errors (up to 3 retries)

Browser Fingerprint Consistency

• UA/Platform alignment: User-Agent, sec-ch-ua, sec-ch-ua-platform, sec-ch-ua-mobile are all consistent (Chrome 133)
• Cookie merge: Set-Cookie headers from Reddit responses are merged back into the session

Structured Output

All --json / --yaml output uses the shared envelope from SCHEMA.md:

ok: true
schema_version: "1"
data: { ... }

When stdout is not a TTY (e.g., piped or invoked by an AI agent), output defaults to YAML. Use OUTPUT=yaml|json|rich|auto to override.

Use as AI Agent Skill

rdt-cli ships with a SKILL.md that teaches AI agents how to use it.

Claude Code / Antigravity

mkdir -p .agents/skills
git clone [e-mail]:jackwener/rdt-cli.git .agents/skills/rdt-cli

# Or just copy the SKILL.md
curl -o .agents/skills/rdt-cli/SKILL.md \
  https://raw.githubusercontent.com/jackwener/rdt-cli/main/SKILL.md

OpenClaw / ClawHub

clawhub install rdt-cli

Project Structure

rdt_cli/
├── __init__.py           # Version
├── __main__.py           # python -m rdt_cli entry point
├── cli.py                # Click entry point & command registration
├── client.py             # Reddit API client (rate-limit, retry, anti-detection)
├── auth.py               # Cookie authentication + TTL refresh
├── constants.py          # URLs, headers, sort options
├── exceptions.py         # Error hierarchy (6 exception types)
├── index_cache.py        # Short-index cache for show/open commands
└── commands/
    ├── _common.py        # Shared helpers (envelope, output routing, formatters)
    ├── auth.py           # login, logout, status, whoami
    ├── browse.py         # feed, popular, all, sub, sub-info, user, user-posts, open
    ├── post.py           # read, show
    ├── search.py         # search, export
    └── social.py         # upvote, save, subscribe, comment

Development

# Install dependencies
uv sync

# Run tests
uv run pytest tests/ -v

# Unit tests only (no network)
uv run pytest tests/ -v -m "not smoke"

# Smoke tests (need cookies)
uv run pytest tests/ -v -m smoke

# Lint
uv run ruff check .

Troubleshooting

Q: No Reddit cookies found

1. Open any browser and visit https://www.reddit.com/
2. Log in with your account
3. Run rdt login (auto-detects browser)

Q: database is locked

Close the browser Cookie database lock — close browser, then retry rdt login.

Q: Session expired

Your cookies have expired. Run rdt logout && rdt login to refresh.

Q: Rate limited

Wait and retry; the built-in exponential backoff handles this automatically.

Q: Requests are slow

The built-in Gaussian jitter delay (~1s between requests) is intentional to mimic natural browsing and avoid triggering Reddit's rate limiting.

---

推荐项目

• xiaohongshu-cli — 小红书搜索、阅读和发帖 CLI
• twitter-cli — Twitter/X 时间线、书签和发推 CLI
• bilibili-cli — Bilibili 视频、用户、搜索与动态 CLI
• discord-cli — Discord 本地优先同步、检索与导出 CLI
• tg-cli — Telegram 本地优先同步、检索与导出 CLI

功能特性

• 🔐 认证 — 自动提取浏览器 Cookie，状态检查，用户信息
• 🏠 浏览 — 首页 Feed、Popular、/r/all
• 📋 子版块 — 浏览任意 subreddit（排序/时间过滤），查看子版块信息
• 📰 帖子 — 阅读帖子和评论树
• 🔢 短索引导航 — rdt show 3 阅读、rdt open 3 浏览器打开
• 🔍 搜索 — 全文搜索，支持子版块、排序、时间过滤
• 📤 导出 — 搜索结果导出为 CSV 或 JSON
• 👤 用户 — 查看用户资料和发帖历史
• ⬆️ 互动 — 点赞/踩、收藏、订阅、评论
• 🛡️ 反风控 — Chrome 133 指纹一致性、高斯抖动延迟、指数退避重试
• 📊 结构化输出 — --yaml / --json，非 TTY 默认输出 YAML
• 📦 稳定 envelope — 参见 SCHEMA.md

安装

# 推荐：uv tool（快速、隔离环境）
uv tool install rdt-cli

# 或者：pipx
pipx install rdt-cli

升级到最新版本：

uv tool upgrade rdt-cli
# 或：pipx upgrade rdt-cli

从源码安装：

git clone [e-mail]:jackwener/rdt-cli.git
cd rdt-cli
uv sync

使用示例

# 认证
rdt login                             # 从浏览器提取 Cookie
rdt status                            # 检查登录状态
rdt whoami                            # 查看用户资料
rdt logout                            # 清除缓存的 Cookie

# 浏览
rdt feed                              # 首页 Feed（需要登录）
rdt popular                           # 热门帖子
rdt all                               # /r/all
rdt sub python                        # 浏览子版块
rdt sub programming -s top -t week    # 排序 + 时间过滤
rdt sub-info python                   # 子版块信息

# 阅读
rdt read 1abc123                      # 按 ID 阅读帖子
rdt show 3                            # 阅读最近一次列表里的第 3 条
rdt open 3                            # 在浏览器打开

# 搜索
rdt search "python async"             # 全局搜索
rdt search "rust vs go" -r programming  # 在子版块内搜索
rdt export "python tips" -n 100 -o tips.csv  # 导出

# 互动（需要登录）
rdt upvote 3                          # 点赞
rdt save 3                            # 收藏
rdt subscribe python                  # 订阅
rdt comment 3 "Great post!"           # 评论

认证策略

rdt-cli 支持浏览器 Cookie 提取来认证 Reddit：

1. 已保存 Cookie — 从 ~/.config/rdt-cli/credential.json 加载
2. 浏览器 Cookie — 自动检测已安装浏览器并提取（支持 Chrome、Firefox、Edge、Brave）

Cookie 保存后有效期 7 天，超时后自动尝试从浏览器刷新。

常见问题

• No Reddit cookies found — 请先在任意浏览器打开 https://www.reddit.com/ 并登录，然后执行 rdt login
• database is locked — 关闭浏览器后重试
• Session expired — Cookie 过期，执行 rdt logout && rdt login 刷新
• Rate limited — 等待重试，内置指数退避会自动处理
• 请求较慢是正常的 — 内置高斯随机延迟（~1s）是为了模拟人类浏览行为，避免触发限速

作为 AI Agent Skill 使用

rdt-cli 自带 SKILL.md，让 AI Agent 能自动学习并使用本工具。

Claude Code / Antigravity

mkdir -p .agents/skills
git clone [e-mail]:jackwener/rdt-cli.git .agents/skills/rdt-cli

OpenClaw / ClawHub

clawhub install rdt-cli

License

Apache-2.0