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
92 lines
3.7 KiB
Markdown
92 lines
3.7 KiB
Markdown
# discourse-cli
|
|
|
|
A Docker container that lets an AI agent (or a human) read, post, reply,
|
|
search, and discuss on a [Discourse](https://www.discourse.org/) 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):
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# then edit .env:
|
|
# DISCOURSE_URL=https://discourse.example.com
|
|
# DISCOURSE_API_KEY=abc123...
|
|
# DISCOURSE_API_USERNAME=your-username
|
|
```
|
|
|
|
## Build
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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. |
|