mrcharles
d4e9fd693f
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
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. |