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