KNEL-AIMiddleware/tooling-cli/discourse/README.md

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

Credentials live in the centralized credential store at ~/.creds/discourse.env (see tooling-cli/KNELCredsManager). It holds:

DISCOURSE_URL=https://discourse.example.com
DISCOURSE_API_KEY=abc123...
DISCOURSE_API_USERNAME=your-username

Use .env.example in this directory as a template if you need to create one. Permissions: directory 700, the env file 600 (owner read/write only).

Build

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

A prebuilt image is also available in the Gitea registry:

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

Usage

Invoke the container directly with docker run. Pass credentials from the centralized store via --env-file:

docker run --rm --env-file ~/.creds/discourse.env \
    git.knownelement.com/reachableceo/discourse-cli:latest whoami

docker run --rm --env-file ~/.creds/discourse.env \
    git.knownelement.com/reachableceo/discourse-cli:latest ls

docker run --rm --env-file ~/.creds/discourse.env \
    git.knownelement.com/reachableceo/discourse-cli:latest show 42

docker run --rm --env-file ~/.creds/discourse.env \
    git.knownelement.com/reachableceo/discourse-cli:latest create -c 5 -t "Hello" -b "Body text"

docker run --rm --env-file ~/.creds/discourse.env \
    git.knownelement.com/reachableceo/discourse-cli:latest reply 42 -b "Nice point"

To use a locally built image instead of the registry image, either set DISCOURSE_CLI_IMAGE or swap the image tag for kneldevstack-aimiddleware-discourse-cli:latest.

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.

Validation

./validate.sh

Runs a full live read/write cycle against the configured instance (credential check, whoami, categories, topics, show, search, create+reply+update+delete cleanup). Credentials are read from ~/.creds/discourse.env by default; override with DISCOURSE_ENV_FILE.