mrcharles
ecffb4e598
Consolidate the discourse-cli source into tooling-cli/discourse/
(CLI source, Dockerfile, README, AGENTS.md, validate.sh) with all
documentation rewritten to invoke the container via raw docker run
and credentials from the centralized ~/.creds/discourse.env store.
No bin/ wrapper, no system-dependent paths in the docs.
Removes the old discourse-cli/ subdirectory and updates the
KNELCredsManager consumer table to reference the container directly.
💘 Generated with Crush
Assisted-by: Crush:glm-5.2
118 lines
4.5 KiB
Markdown
118 lines
4.5 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
|
|
|
|
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
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
./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`.
|