# 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`.