public-clis rdt-cli — Reddit CLI Tool
Binary: rdt
Credentials: browser cookies (auto-extracted via browser-cookie3)
Setup
# Install (requires Python 3.10+)
uv tool install rdt-cli
# Or: pip install rdt-cli
# Upgrade
uv tool upgrade rdt-cli
Authentication
IMPORTANT FOR AGENTS: Before executing ANY rdt command that requires auth, check if credentials exist.
Step 0: Check if already authenticated
rdt status --json 2>/dev/null | jq -r '.data.authenticated' | grep -q true && echo "AUTH_OK" || echo "AUTH_NEEDED"
If AUTH_OK, skip to Command Reference.
If AUTH_NEEDED, proceed to Step 1.
Step 1: Guide user to authenticate
Ensure user is logged into reddit.com in a supported browser (Chrome, Firefox, Edge, Brave, Arc, Chromium, Opera, Vivaldi, Safari, LibreWolf). Then:
rdt login
Verify with:
rdt status
rdt whoami --json | jq '.data.name // .data._session.username'
Step 2: Handle common auth issues
| Symptom | Agent action |
|---|---|
No Reddit cookies found |
Guide user to login to reddit.com in browser |
Session expired |
Run rdt logout && rdt login |
database is locked |
Close browser, then retry |
Agent Defaults
All machine-readable output uses the envelope documented in SCHEMA.md.
Payloads live under .data.
- Non-TTY stdout → auto YAML
--json/--yaml→ explicit format--compact→ fewer fields (agent token-efficient)--output file.json→ save structured output to file- Rich output → stderr (safe for pipes:
rdt search X --json | jq .data) - Most read commands work without auth (public Reddit JSON API)
- Write actions (upvote, save, subscribe) require auth + built-in 1.5-4s delay
Command Reference
Browsing
| Command | Description | Example |
|---|---|---|
rdt feed |
Browse home feed (requires login) | rdt feed -n 10 --json |
rdt feed --subs-only |
Subscriptions-only feed (no algorithm, sorted by time) | rdt feed --subs-only -n 5 --json |
rdt popular |
Browse /r/popular | rdt popular -n 5 --json |
rdt all |
Browse /r/all | rdt all -n 10 --compact --json |
rdt sub <name> |
Browse a subreddit | rdt sub python -s top -t week |
rdt sub-info <name> |
View subreddit info | rdt sub-info rust --json |
rdt user <name> |
View user profile | rdt user spez --json |
rdt user-posts <name> |
View user's posts | rdt user-posts spez -n 5 --json |
rdt user-comments <name> |
View user's comments | rdt user-comments spez -n 5 --json |
rdt saved |
View your saved items | rdt saved -n 10 --json |
rdt upvoted |
View your upvoted posts | rdt upvoted -n 10 --json |
rdt open <id_or_index> |
Open post in browser | rdt open 3 |
Reading
| Command | Description | Example |
|---|---|---|
rdt read <post_id> |
Read a post + comments | rdt read 1abc123 --json |
rdt read <post_id> --expand-more |
Expand top-level more comments |
rdt read 1abc123 --expand-more --json |
rdt show <index> |
Read by short-index | rdt show 3 |
rdt show <index> --expand-more |
Expand more comments from cached result |
rdt show 3 --expand-more --json |
rdt whoami |
View your profile (karma, age) | rdt whoami --json |
Search & Export
| Command | Description | Example |
|---|---|---|
rdt search <query> |
Search posts | rdt search "python async" -s top -t year |
rdt search <query> -r <sub> |
Search in subreddit | rdt search "error" -r rust --json |
rdt search <query> -o f.json |
Search + save to file | rdt search "ML" -n 50 -o results.json |
rdt export <query> |
Export to CSV/JSON | rdt export "ML" -n 50 -o results.csv |
Interactions (require auth)
| Command | Description | Example |
|---|---|---|
rdt upvote <id_or_index> |
Upvote | rdt upvote 3 |
rdt upvote <id> --down |
Downvote | rdt upvote 3 --down |
rdt upvote <id> --undo |
Remove vote | rdt upvote 3 --undo |
rdt save <id_or_index> |
Save post | rdt save 3 |
rdt save <id> --undo |
Unsave | rdt save 3 --undo |
rdt subscribe <sub> |
Subscribe | rdt subscribe python |
rdt subscribe <sub> --undo |
Unsubscribe | rdt subscribe python --undo |
rdt comment <id> <text> |
Post a comment | rdt comment 3 "Great post!" |
Account
| Command | Description |
|---|---|
rdt login |
Extract cookies from browser |
rdt logout |
Clear cached cookies |
rdt status |
Check authentication status |
rdt whoami |
View detailed profile info |
Listing Options
All listing commands (feed, popular, all, sub, user-posts, user-comments, saved, upvoted, search) support:
| Flag | Description |
|---|---|
--json |
JSON output (with SCHEMA envelope) |
--yaml |
YAML output (with SCHEMA envelope) |
-o, --output FILE |
Save structured output to file |
--full-text |
Show full title without truncation |
-c, --compact |
Agent-friendly compact output (fewer fields) |
Feed-specific Options
| Flag | Description |
|---|---|
--subs-only |
Show only posts from subscribed subreddits (sorted by time, no algorithm) |
--max-subs N |
Max subscriptions to fetch (default: 20) |
Agent Workflow Examples
Browse → Read → Upvote pipeline
rdt sub python -s top -t week -n 5
rdt show 1 --expand-more
rdt upvote 1
Search → Export pipeline (structured)
rdt search "machine learning" -s top --compact --json | jq '.data'
rdt export "machine learning" -n 100 -o ml_posts.csv
Search → Save to file
rdt search "rust async" -n 50 -o results.json
rdt search "python tips" -n 20 --compact -o tips.json
User research
rdt user spez --json | jq '.data | {name, link_karma, comment_karma}'
rdt user-posts spez -n 10 --compact --json
rdt user-comments spez -n 10 --compact --json
Saved / Upvoted review
rdt saved -n 20 --compact --json
rdt upvoted -n 20 --compact --json
Subscriptions-only monitoring
rdt feed --subs-only -n 5 --compact --json
rdt feed --subs-only --max-subs 10 -o subs_feed.json
Subreddit discovery
rdt sub-info python --json | jq '.data | {subscribers, accounts_active}'
rdt sub python -s top -t month -n 5 --full-text
Sort Options
- Listing sort:
hot,new,top,rising,controversial,best - Search sort:
relevance,hot,top,new,comments - Time filter (for top/controversial):
hour,day,week,month,year,all - Comment sort:
best,top,new,controversial,old,qa
Error Codes
Structured error codes returned in the error.code field (see SCHEMA.md):
not_authenticated— cookies expired or missingrate_limited— too many requestsnot_found— subreddit/user/post does not existforbidden— private subreddit or blocked userapi_error— upstream Reddit API errorunknown_error— unexpected error
Limitations
- No DMs — cannot access private messages
- No live/streaming — live features not supported
- No media download — cannot download images/videos
- Single account — one set of cookies at a time
- Rate limited — built-in Gaussian jitter (~1s) between requests
- Public API only — uses .json suffix API, not OAuth endpoints
Anti-Detection Notes for Agents
- Do NOT parallelize requests — the built-in rate-limit delay is for account safety
- Write operation delay: 1.5-4s random delay after each write (upvote/save/subscribe/comment)
- Batch operations: add delays between CLI calls when doing bulk work
- Chrome 133 fingerprint: all requests use consistent browser identity
- Exponential backoff: 429/5xx errors are auto-retried with backoff
Safety Notes
- Do not ask users to share raw cookie values in chat logs
- Prefer browser cookie extraction over manual secret copy/paste
- If auth fails, ask the user to re-login via
rdt login - Built-in rate-limit delay protects accounts; do not bypass it