reddit-post

A command-line tool for submitting posts to Reddit. Lightweight wrapper around PRAW for text and link submissions.

Prerequisites

• Python 3.9+
• A Reddit account
• A Reddit "script" app (created via https://www.reddit.com/prefs/apps)

Installation

pip install -r requirements.txt

Make the script available on your PATH:

# Option A: symlink into ~/.local/bin
ln -sf "$(pwd)/reddit-post" ~/.local/bin/reddit-post

# Option B: add the directory to PATH
export PATH="$PWD:$PATH"

Setup

Run the interactive setup to configure your Reddit API credentials:

reddit-post setup

This will walk you through creating a Reddit app and test the connection before saving credentials to ~/.reddit/config.json.

Manual config

Alternatively, copy and fill in the example config:

cp config.example.json ~/.reddit/config.json
$EDITOR ~/.reddit/config.json

Required Reddit app type: "script" (personal use script) Redirect URI: http://localhost:8080 (required by Reddit but unused)

Usage

Text post

reddit-post text python "My title" "Body text here"

Link post

reddit-post link programming "Check this out" "https://example.com"

Optional flags

reddit-post text my_subreddit "Title" "Body" --flair "Discussion" --nsfw

Check status

reddit-post status

Shows your authenticated username, karma, and rate limit info.

Agent / AI Usage

reddit-post is designed to work well with AI coding agents (Hermes Agent, OpenClaw, Claude Code, Codex, etc.) that can execute CLI commands via their terminal() tool.

How agents interact with this tool

Agents access Reddit posting through shell commands only — they can run:

reddit-post text python "Post title" "Post body here"
reddit-post link programming "Cool link" "https://example.com"
reddit-post status
reddit-post setup

The agent reads stdout for success/failure — it parses the output and the post URL returned on success. No special JSON output mode is needed.

Recommended agent workflow

1. Draft — The agent drafts the post (title + body) based on your instructions
2. Review — You review and approve the draft before it goes live
3. Post — The agent runs the command and confirms the result

This is the default workflow used by the Hermes Agent Reddit skill.

Example agent prompts

Post this to r/python: "My title" / "Body text here"

Run reddit-post status to check my credentials

Post the article at https://example.com to r/programming

What agents can't do via this tool

• Edit posts — Reddit's API doesn't expose post editing. Edits require the web UI.
• Comment or reply — This tool is for post submission only, not thread interaction.
• Bypass subreddit rules — Agents should check subreddit rules before posting (subreddit-specific title formats, karma minimums, etc.).

Integration notes for agent developers

• The tool exits non-zero on failure; agents should check exit_code.
• Credentials live at ~/.reddit/config.json — this is a sensitive file and should not be read into LLM context.
• PRAW handles rate limiting internally; no special backoff logic needed from the agent.
• The --flair and --nsfw flags are optional but required by some subreddits.

Reddit API rate limits

Free script apps get 100 requests per minute via OAuth. More than enough for sporadic posting. See https://old.reddit.com/dev/api for details.

License

MIT