rdt-cli 0.2.0__tar.gz

rdt_cli-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_call:
+
+jobs:
+  lint-and-test:
+    name: Lint and test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run ruff
+        run: uv run ruff check .
+
+      - name: Run tests
+        run: uv run python -m pytest -q
+
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    needs: lint-and-test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Build distribution
+        run: uv build

rdt_cli-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

rdt_cli-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+dist/
+.venv/
+*.egg-info/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/

rdt_cli-0.2.0/PKG-INFO

@@ -0,0 +1,398 @@
+Metadata-Version: 2.4
+Name: rdt-cli
+Version: 0.2.0
+Summary: A CLI for Reddit — browse feeds, read posts, search, and interact via terminal 📖
+Project-URL: Homepage, https://github.com/jackwener/rdt-cli
+Project-URL: Repository, https://github.com/jackwener/rdt-cli
+Project-URL: Issues, https://github.com/jackwener/rdt-cli/issues
+Author-email: jackwener <jakevingoo@gmail.com>
+License-Expression: Apache-2.0
+Keywords: api,cli,rdt,reddit,terminal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: browser-cookie3>=0.19
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# rdt-cli
+
+[![CI](https://github.com/jackwener/rdt-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/jackwener/rdt-cli/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/rdt-cli.svg)](https://pypi.org/project/rdt-cli/)
+[![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue.svg)](https://pypi.org/project/rdt-cli/)
+
+A CLI for Reddit — browse feeds, read posts, search, and interact via reverse-engineered API 📖
+
+[English](#features) | [中文](#功能特性)
+
+## More Tools
+
+- [xiaohongshu-cli](https://github.com/jackwener/xiaohongshu-cli) — Xiaohongshu CLI for search, reading, and posting
+- [twitter-cli](https://github.com/jackwener/twitter-cli) — Twitter/X CLI for timelines, bookmarks, and posting
+- [bilibili-cli](https://github.com/jackwener/bilibili-cli) — Bilibili CLI for videos, users, search, and feeds
+- [discord-cli](https://github.com/jackwener/discord-cli) — Discord CLI for local-first sync, search, and export
+- [tg-cli](https://github.com/jackwener/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](./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
+
+```bash
+# Recommended: uv tool (fast, isolated)
+uv tool install rdt-cli
+
+# Or: pipx
+pipx install rdt-cli
+```
+
+Upgrade to the latest version:
+
+```bash
+uv tool upgrade rdt-cli
+# Or: pipx upgrade rdt-cli
+```
+
+From source:
+
+```bash
+git clone git@github.com:jackwener/rdt-cli.git
+cd rdt-cli
+uv sync
+```
+
+## Usage
+
+```bash
+# ─── 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](./SCHEMA.md):
+```yaml
+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`](./SKILL.md) that teaches AI agents how to use it.
+
+### Claude Code / Antigravity
+
+```bash
+mkdir -p .agents/skills
+git clone git@github.com: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
+
+```bash
+clawhub install rdt-cli
+```
+
+## Project Structure
+
+```text
+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
+
+```bash
+# 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](https://github.com/jackwener/xiaohongshu-cli) — 小红书搜索、阅读和发帖 CLI
+- [twitter-cli](https://github.com/jackwener/twitter-cli) — Twitter/X 时间线、书签和发推 CLI
+- [bilibili-cli](https://github.com/jackwener/bilibili-cli) — Bilibili 视频、用户、搜索与动态 CLI
+- [discord-cli](https://github.com/jackwener/discord-cli) — Discord 本地优先同步、检索与导出 CLI
+- [tg-cli](https://github.com/jackwener/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](./SCHEMA.md)
+
+## 安装
+
+```bash
+# 推荐：uv tool（快速、隔离环境）
+uv tool install rdt-cli
+
+# 或者：pipx
+pipx install rdt-cli
+```
+
+升级到最新版本：
+
+```bash
+uv tool upgrade rdt-cli
+# 或：pipx upgrade rdt-cli
+```
+
+从源码安装：
+
+```bash
+git clone git@github.com:jackwener/rdt-cli.git
+cd rdt-cli
+uv sync
+```
+
+## 使用示例
+
+```bash
+# 认证
+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`](./SKILL.md)，让 AI Agent 能自动学习并使用本工具。
+
+### Claude Code / Antigravity
+
+```bash
+mkdir -p .agents/skills
+git clone git@github.com:jackwener/rdt-cli.git .agents/skills/rdt-cli
+```
+
+### OpenClaw / ClawHub
+
+```bash
+clawhub install rdt-cli
+```
+
+## License
+
+Apache-2.0