Skip to content

public-clis/rdt-cli

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

16 Commits
.github/workflows
.github/workflows
 
 
rdt_cli
rdt_cli
 
 
tests
tests
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
SCHEMA.md
SCHEMA.md
 
 
SKILL.md
SKILL.md
 
 
pyproject.toml
pyproject.toml
 
 
uv.lock
uv.lock
 
 

Repository files navigation

rdt-cli

CI PyPI version Python

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, /r/all, and subscription-only feed (--subs-only)
  • 📋 Subreddits — browse any subreddit with sort/time filters, view subreddit info
  • 📰 Posts — read posts and comment trees with syntax highlighting
  • 💬 Expanded comments — --expand-more loads additional more comments entries
  • 🔢 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, post history, comment history, saved and upvoted items
  • ⬆️ 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 [email protected]: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 feed --subs-only                  # Subscriptions-only feed (no algorithm)
rdt feed --subs-only -n 5 --max-subs 10  # Limit per-sub posts and max subs
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
rdt user-comments spez                # User's comments
rdt saved                             # Your saved posts/items
rdt upvoted                           # Your upvoted 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 read 1abc123 --expand-more        # Expand top-level "more comments"
rdt show 3                            # Read result #3 from last listing
rdt show 3 --expand-more              # Expand additional comments from cache-backed post
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.

Skills CLI (Recommended)

npx skills add jackwener/rdt-cli
Flag Description
-g Install globally (user-level, shared across projects)
-a claude-code Target a specific agent
-y Non-interactive mode

Manual Install

mkdir -p .agents/skills
git clone [email protected]:jackwener/rdt-cli.git .agents/skills/rdt-cli

OpenClaw / ClawHub (Deprecated)

⚠️ ClawHub 安装方式已过时，不再支持。请使用上方的 Skills 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, user-comments, saved, upvoted, 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、纯订阅 Feed（--subs-only）
  • 📋 子版块 — 浏览任意 subreddit（排序/时间过滤），查看子版块信息
  • 📰 帖子 — 阅读帖子和评论树
  • 💬 评论展开 — --expand-more 可展开额外评论
  • 🔢 短索引导航 — 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 [email protected]:jackwener/rdt-cli.git
cd rdt-cli
uv sync

使用示例

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

# 浏览
rdt feed                              # 首页 Feed（需要登录）
rdt feed --subs-only                  # 纯订阅 Feed（无算法推荐）
rdt feed --subs-only -n 5 --max-subs 10  # 限制每个 sub 帖子数和最大 sub 数
rdt popular                           # 热门帖子
rdt all                               # /r/all
rdt sub python                        # 浏览子版块
rdt sub programming -s top -t week    # 排序 + 时间过滤
rdt sub-info python                   # 子版块信息
rdt user spez                         # 用户资料
rdt user-posts spez                   # 用户发帖
rdt user-comments spez                # 用户评论
rdt saved                             # 你的收藏
rdt upvoted                           # 你的点赞

# 阅读
rdt read 1abc123                      # 按 ID 阅读帖子
rdt read 1abc123 --expand-more        # 展开更多评论
rdt show 3                            # 阅读最近一次列表里的第 3 条
rdt show 3 --expand-more              # 展开缓存帖子里的更多评论
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 能自动学习并使用本工具。

Skills CLI（推荐）

npx skills add jackwener/rdt-cli
参数 说明
-g 全局安装（用户级别，跨项目共享）
-a claude-code 指定目标 Agent
-y 非交互模式

手动安装

mkdir -p .agents/skills
git clone [email protected]:jackwener/rdt-cli.git .agents/skills/rdt-cli

OpenClaw / ClawHub（已过时）

⚠️ ClawHub 安装方式已过时，不再支持。请使用上方的 Skills CLI 或手动安装。

License

Apache-2.0

About

Reddit in your terminal 📖 — Browse feeds, read posts, search, upvote, save, subscribe

Resources

Readme
Activity
Custom properties

Stars

289 stars

Watchers

1 watching

Forks

30 forks
Report repository

Releases

6 tags

Packages

 
 
 

Contributors

Languages