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