feat: add redmine-cli containerized CLI tool

Merge the redmine-cli work from the EnableAI repo into KNEL-AIMiddleware as the canonical home for AI middleware. This is a standalone CLI (python-redmine 2.5.0) that lists, shows, creates, updates, and closes Redmine issues via docker run. Complements the existing mcp-redmine MCP server (protocol-native) with a direct-invocation tool for interactive use. Verified end-to-end against projects.knownelement.com: whoami, projects, statuses, list, show, create, update, and close all tested successfully. Also records host-cleanliness conventions (docker/tea only on host; custom images to Gitea registry) in AGENTS.md, and adds a CLI Tools section to STATUS.md.
2026-07-30 12:09:44 -05:00
parent 280ebc2e67
commit b69e70e0a1
8 changed files with 549 additions and 0 deletions
@@ -0,0 +1,97 @@
+# redmine-cli
+
+A Docker container that lets an AI agent (or a human) access, edit, and close
+Redmine issues through the Redmine REST API. Built on the
+[`python-redmine`](https://python-redmine.com) library with a small command-line
+wrapper.
+
+## Requirements
+
+- Docker on the host.
+- A Redmine instance with REST web services enabled
+  (Administration → Settings → API → Enable REST API).
+- A Redmine API key for the user the agent will act as
+  (My account → API access key → Show / Reset).
+
+## Configuration
+
+Copy the env template and fill in real values (the `.env` is gitignored):
+
+```bash
+cp .env.example .env
+# then edit .env:
+#   REDMINE_URL=https://your-redmine.example.com
+#   REDMINE_API_KEY=abc123...
+```
+
+## Build
+
+```bash
+docker build -t kneldevstack-aimiddleware-redmine-cli .
+```
+
+A prebuilt image is also available in the Gitea registry:
+
+```
+git.knownelement.com/reachableceo/redmine-cli:latest
+```
+
+## Usage
+
+### Via the repo wrapper (loads `.env` automatically)
+
+```bash
+bin/redmine whoami
+bin/redmine list --assigned-to-me
+bin/redmine show 123
+bin/redmine close 123 --notes "work complete"
+```
+
+### Via docker directly (from the repo root)
+
+```bash
+docker run --rm --env-file .env kneldevstack-aimiddleware-redmine-cli whoami
+docker run --rm --env-file .env kneldevstack-aimiddleware-redmine-cli list --assigned-to-me
+```
+
+## Commands
+
+| Command                          | Description                                            |
+| -------------------------------- | ------------------------------------------------------ |
+| `whoami`                         | Show the authenticated user (also a connection test).  |
+| `projects`                       | List projects (id, identifier, name).                  |
+| `statuses`                       | List issue statuses and which are "closed".            |
+| `list` (`ls`)                    | List issues. Filters below.                            |
+| `show <id>`                      | Show full issue detail incl. note history.             |
+| `create`                         | Create an issue (`--project`, `--subject`, ...).       |
+| `update <id>`                    | Update an issue (status, notes, assignee, done, ...).  |
+| `close <id>`                     | Close an issue (first closed status, done ratio 100%). |
+
+### `list` filters
+
+- `-m, --assigned-to-me` — only issues assigned to the current user
+- `-a, --assigned-to <id>` — filter by assignee user id
+- `-p, --project <id|identifier>` — filter by project
+- `-s, --status <name|id|open|closed>` — filter by status
+- `-l, --limit <n>` — max results (default 50)
+- `--sort <spec>` — Redmine sort spec
+  (default `priority:desc,updated_on:desc`)
+
+### `update` / `create` options
+
+- `--status <name|id>` — status name (case-insensitive) or numeric id
+- `-n, --notes <text>` — add a journal note
+- `-a, --assigned-to <id>` — assignee user id
+- `--done-ratio <0-100>` — percent complete
+- `--subject <text>` — change the subject (`update`/`create`)
+- `--priority <id>` — priority id
+- `-d, --description <text>` — description (`create` only)
+- `-t, --tracker <id>` — tracker id (`create` only)
+
+## Environment variables
+
+| Variable          | Required | Description                          |
+| ----------------- | -------- | ------------------------------------ |
+| `REDMINE_URL`     | yes      | Base URL of the Redmine instance.    |
+| `REDMINE_API_KEY` | yes      | API key of the acting user.          |
+| `REDMINE_CLI_IMAGE` | no     | Override the image tag used by `bin/redmine` (default `git.knownelement.com/reachableceo/redmine-cli:latest`). |