Files

T

mrcharles d4e9fd693f feat: add discourse-cli for Discourse forum integration

A standalone CLI container (following the redmine-cli pattern) that
lets AI agents and humans read, post, reply, search, and discuss on a
Discourse forum via the REST API. Uses three environment variables
(DISCOURSE_URL, DISCOURSE_API_KEY, DISCOURSE_API_USERNAME) for auth.

Commands: whoami, categories, cat-info, topics/ls, show, create, reply,
update, delete, search, notifications.

Fully validated end-to-end (10/10 checks) against a live Discourse
instance: credential auth, whoami, categories, topics, show, search,
and full write cycle (create + reply + update + delete).

Includes validate.sh for repeatable end-to-end testing using
containerized curl + the CLI image.

💘 Generated with Crush

Assisted-by: Crush:glm-5.2

2026-07-30 16:39:17 -05:00

3.7 KiB

Raw Permalink Blame History

discourse-cli

A Docker container that lets an AI agent (or a human) read, post, reply, search, and discuss on a Discourse forum through the Discourse REST API. A small Python CLI built on requests.

Requirements

Docker on the host.
A Discourse instance with API access enabled (Admin → API → "All users" or "Single user" API key).
An API key and the username the key acts as.

Configuration

Copy the env template and fill in real values (the .env is gitignored):

cp .env.example .env
# then edit .env:
#   DISCOURSE_URL=https://discourse.example.com
#   DISCOURSE_API_KEY=abc123...
#   DISCOURSE_API_USERNAME=your-username

Build

docker build -t kneldevstack-aimiddleware-discourse-cli .

A prebuilt image is also available in the Gitea registry:

git.knownelement.com/reachableceo/discourse-cli:latest

Usage

Via docker directly (from this directory)

docker run --rm --env-file .env kneldevstack-aimiddleware-discourse-cli whoami
docker run --rm --env-file .env kneldevstack-aimiddleware-discourse-cli ls
docker run --rm --env-file .env kneldevstack-aimiddleware-discourse-cli show 42
docker run --rm --env-file .env kneldevstack-aimiddleware-discourse-cli create -c 5 -t "Hello" -b "Body text"
docker run --rm --env-file .env kneldevstack-aimiddleware-discourse-cli reply 42 -b "Nice point"

Commands

Command	Description
`whoami`	Show the authenticated user (also a connection test).
`categories`	List categories (id, slug, topic count).
`cat-info <cat>`	Show details of a category (id or slug).
`topics` (`ls`)	List topics (latest, or filtered by category/new/unread).
`show <topic_id>`	Show a topic with all its posts.
`create`	Create a topic (`--category`, `--title`, `--body`, `--tags`).
`reply <topic_id>`	Reply to a topic (`--body`, optional `--reply-to`).
`update <post_id>`	Update a post (`--body`).
`delete <post_id>`	Delete a post.
`search <query>`	Search the forum.
`notifications`	List your notifications.

`topics` / `ls` filters

-c, --category <id|slug> — only topics in this category
-n, --new — only new (unread tracking) topics
-u, --unread — only unread topics
-p, --page <n> — page number (default 0)

`create` options

-c, --category <id|slug> — category to post in
-t, --title <text> — topic title (required)
-b, --body <text> — post body, raw text or markdown (required)
--tags <a,b,c> — comma-separated tags

`reply` options

-b, --body <text> — reply body, raw text or markdown (required)
-r, --reply-to <post_number> — reply to a specific post number (optional)

Environment variables

Variable	Required	Description
`DISCOURSE_URL`	yes	Base URL of the Discourse instance.
`DISCOURSE_API_KEY`	yes	API key ("All users" or "Single user").
`DISCOURSE_API_USERNAME`	yes	Username the API key acts as.

3.7 KiB Raw Permalink Blame History