mrcharles
b69e70e0a1
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.
98 lines
3.5 KiB
Markdown
98 lines
3.5 KiB
Markdown
# 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`). |
|