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

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

Reading

Search & Export

Interactions (require auth)

Account

Listing Options

All listing commands (feed, popular, all, sub, user-posts, user-comments, saved, upvoted, search) support:

Feed-specific Options

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 missing
• rate_limited — too many requests
• not_found — subreddit/user/post does not exist
• forbidden — private subreddit or blocked user
• api_error — upstream Reddit API error
• unknown_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