README
¶
redmine-cli
A command-line interface for Redmine project management.
Installation · Getting Started · AI Agents
Installation
Homebrew (macOS, Linux):
brew install aarondpn/tap/redmine
Install script (macOS, Linux):
curl -fsSL https://raw.githubusercontent.com/aarondpn/redmine-cli/main/install.sh | bash
PowerShell (Windows):
irm https://raw.githubusercontent.com/aarondpn/redmine-cli/main/install.ps1 | iex
Or download a binary from GitHub Releases. Update with redmine update. More options: installation docs.
Getting Started
# Configure your Redmine server and API key
redmine auth login
# List issues
redmine issues list
# View a specific issue
redmine issues view 123
# Log time
redmine time log
# Script it: JSON output filtered with the built-in --jq
redmine issues list --project myproject --jq '.[].id'
redmine issues get 123 --jq '.status.name'
Run redmine --help to see all available commands.
-o json prints machine-readable JSON, and -q/--jq <expression> filters it (strings are printed raw, everything else as JSON). Errors always go to stderr; in JSON mode they are a single-line {"error": {...}} envelope on the last line of stderr, stdout stays empty and the exit code is non-zero. See Output formats.
Using with AI Agents
redmine-cli ships an Agent Skill (the open SKILL.md standard, supported by 35+ agents) and a built-in MCP server. Both are vendor-neutral - pick the one-liner that matches your tool:
| Tool | One-line install |
|---|---|
| Any agent (skill) | npx skills add aarondpn/redmine-cli |
| Any MCP host | redmine mcp serve (then add to host config) |
| Docker (MCP only) | docker run -i --rm -e REDMINE_SERVER -e REDMINE_API_KEY ghcr.io/aarondpn/redmine-mcp |
| Claude Code | /plugin marketplace add aarondpn/redmine-cli then /plugin install redmine |
| Codex CLI | codex plugin marketplace add aarondpn/redmine-cli then /plugins (install Redmine from the added marketplace) |
| Gemini CLI | gemini extensions install https://github.com/aarondpn/redmine-cli |
The skill teaches the agent the non-obvious parts of the CLI (output formats, name resolution, pagination, common workflows). The MCP server exposes the same operations as typed tool calls, read-only by default, with per-group / per-tool allow- and deny-lists.
Full configuration, host-specific snippets (Claude Desktop, Cursor, Zed, VS Code), and write-tool gating: see the AI Agent Integration guide.
Development
Local E2E testing against a real Redmine instance (Docker, supported on Redmine 4.2, 5.1, 6.1, 7.0): see e2e/README.md.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
mcpgen
command
|
|
|
redmine
command
|
|
|
Package e2e contains build-tagged end-to-end tests that exercise the CLI against a real Redmine instance started locally via Docker Compose.
|
Package e2e contains build-tagged end-to-end tests that exercise the CLI against a real Redmine instance started locally via Docker Compose. |
|
internal
|
|
|
browser
Package browser opens URLs in the user's default web browser.
|
Package browser opens URLs in the user's default web browser. |
|
cmd/attachment
Package attachment implements the `redmine attachments` command group, which surfaces the Redmine REST Attachments API so users (and agents) can inspect attachment metadata and download the raw bytes without dropping down to `redmine api` plus a manual `curl` with a hand-extracted API key.
|
Package attachment implements the `redmine attachments` command group, which surfaces the Redmine REST Attachments API so users (and agents) can inspect attachment metadata and download the raw bytes without dropping down to `redmine api` plus a manual `curl` with a hand-extracted API key. |
|
cmd/enumeration
Package enumeration implements the priorities, activities and document-categories command groups.
|
Package enumeration implements the priorities, activities and document-categories command groups. |
|
cmd/files
Package files implements the `redmine files` command group, which surfaces the Redmine REST Files API so users can list and upload project-level artifacts without dropping down to `redmine api`.
|
Package files implements the `redmine files` command group, which surfaces the Redmine REST Files API so users can list and upload project-level artifacts without dropping down to `redmine api`. |
|
cmd/mcp
Package mcp wires the Model Context Protocol server subcommand into the Redmine CLI.
|
Package mcp wires the Model Context Protocol server subcommand into the Redmine CLI. |
|
cmd/news
Package news implements the news command group.
|
Package news implements the news command group. |
|
mcpserver
Package mcpserver implements a Model Context Protocol server that exposes the redmine-cli API surface to MCP-compatible hosts (Claude Desktop, Claude Code, Cursor, etc.).
|
Package mcpserver implements a Model Context Protocol server that exposes the redmine-cli API surface to MCP-compatible hosts (Claude Desktop, Claude Code, Cursor, etc.). |
|
secrets
Package secrets provides an optional, opt-in abstraction over the OS keyring for storing user credentials.
|
Package secrets provides an optional, opt-in abstraction over the OS keyring for storing user credentials. |
|
testutil
Package testutil provides shared test helpers for command-layer tests.
|
Package testutil provides shared test helpers for command-layer tests. |
|
testutil/contract
Package contract compares the JSON Redmine returned for a resource with the JSON the CLI or the MCP server produced for the same resource, and reports every place where data was dropped or altered on the way.
|
Package contract compares the JSON Redmine returned for a resource with the JSON the CLI or the MCP server produced for the same resource, and reports every place where data was dropped or altered on the way. |
|
textsafe
Package textsafe neutralizes untrusted text before it reaches a terminal.
|
Package textsafe neutralizes untrusted text before it reaches a terminal. |