Every Redmine feature, plus a local mirror that finally answers the cross-project questions the Roadmap page never could.
Redmine's REST API is deeply relational but strictly request-per-entity — no burndown endpoint, no workload endpoint, no staleness concept. This CLI absorbs the full REST surface (issues, projects, time entries, wiki, versions, memberships, and more) and adds a synced SQLite mirror underneath, so burndown, workload, cycle-time, and blocker-chain questions resolve to one local query instead of dozens of live requests.
Learn more at Redmine.
Authentication
Redmine is self-hosted, so two things are required instead of just a key: REDMINE_URL (your instance's base URL) and REDMINE_API_KEY (from your account's My Account page, or Administration > Settings > API for admins). Both are sent as-is — REDMINE_API_KEY becomes the X-Redmine-API-Key header on every request.
Quick Start
# Verify REDMINE_URL and REDMINE_API_KEY are set and the instance is reachable, without making a real call.
redmine-pp-cli doctor --dry-run
# Pull a full local mirror so search, digest, and every transcendence command have data to work with. The status_id=* override is required to include closed issues — Redmine's default issue list only returns open ones.
redmine-pp-cli sync --resources issues-json,projects-json,time-entries-json,users-json --full --resource-param issues-json:status_id=*
# Confirm the sync worked by listing open issues in a known project.
redmine-pp-cli issues-json get-issues --project-id demo --status-id o --json
# See what changed in the last week across issues assigned to you.
redmine-pp-cli digest --since 7d --mine
# Check whether anyone on the project is carrying too much open work.
redmine-pp-cli workload --project demo
Unique Features
These capabilities aren't available in any other tool for this API.
Local state that compounds
-
roadmap burndown — See open/closed issue counts, average completion, and logged-vs-estimated hours for a release version — the Roadmap page Redmine never exposed as an API.
Reach for this before a release-readiness call instead of hand-counting issues in the web UI.
redmine-pp-cli roadmap burndown 1.0 --project demo --json
-
workload — See every assignee's open-issue count and estimated hours in one aggregate view, with a flag for anyone over threshold.
Use this before sprint planning to catch overload without opening every engineer's issue list one by one.
redmine-pp-cli workload --project demo --threshold 5 --json
-
issues stale — Find open issues nobody has touched in N days — Redmine has no built-in staleness concept.
Use this for triage sweeps to surface issues that fell through the cracks, not recently active ones.
redmine-pp-cli issues stale --project demo --days 14 --json
-
digest — A personal activity report of what was created, updated, or closed in a time window, optionally scoped to issues assigned to or watched by you.
Use this for a 'what did I miss' catch-up instead of paging through each project's activity feed by hand.
redmine-pp-cli digest --since 7d --mine --json
-
issues cycle-time — Average days from creation to close, grouped by tracker or project — real duration math the API can't do.
Use this to spot which issue types are taking longer than they should to resolve.
redmine-pp-cli issues cycle-time --group-by tracker --project demo --json
-
issues blockers — Walk the full multi-hop 'blocks'/'blocked by' dependency chain for an issue, not just its direct relations.
Use this before starting work on an issue to confirm it isn't blocked three hops away by something you haven't seen yet.
redmine-pp-cli issues blockers 3 --depth 3 --json
Recipes
Triage open bugs with a narrow agent payload
redmine-pp-cli issues-json get-issues --project-id demo --status-id o --tracker-id 1 --agent --select id,subject,tracker.name,priority.name
Nested tracker/priority/status objects on every issue add up fast across a full project; --select keeps only the fields an agent actually needs to triage.
Find issues nobody has touched in two weeks
redmine-pp-cli issues stale --project demo --days 14 --json
Surfaces open issues with no recent activity, which Redmine itself has no concept of.
See who's carrying the most open work
redmine-pp-cli workload --project demo --threshold 5
One command instead of opening each engineer's assigned-issue list to eyeball the count.
Trace why an issue is blocked
redmine-pp-cli issues blockers 3 --depth 3
Walks the full transitive blocker chain instead of clicking through each linked issue one hop at a time.
Check release readiness for a version
redmine-pp-cli roadmap burndown 1.0 --project demo --json
Open/closed counts, average done_ratio, and hours variance for the version in one call, replacing a manual Roadmap-page count.
Usage
Run redmine-pp-cli --help for the full command reference and flag list.
Paths & environment variables
This CLI separates local files into four path kinds:
| Kind | Contents |
|---|
config | User-editable settings such as config.toml and saved profiles |
data | Durable local data: credentials.toml, data.db, cookies, browser-session proof files, and other auth sidecars |
state | Runtime state such as persisted queries, jobs, and teach.log |
cache | Regenerable HTTP/cache files |
Each kind resolves independently. The ladder is:
- Per-kind env var:
REDMINE_CONFIG_DIR, REDMINE_DATA_DIR, REDMINE_STATE_DIR, or REDMINE_CACHE_DIR
--home <dir> for this invocationREDMINE_HOME for a flat relocated root- XDG env vars:
XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME
- Platform defaults matching existing installs
For containers and agent sandboxes, prefer a single relocated root:
export REDMINE_HOME=/srv/redmine
redmine-pp-cli doctor
Under REDMINE_HOME=/srv/redmine, the four dirs resolve to /srv/redmine/config, /srv/redmine/data, /srv/redmine/state, and /srv/redmine/cache.
MCP servers do not receive CLI flags from the host. Put relocation in the host env block:
{
"mcpServers": {
"redmine": {
"command": "redmine-pp-mcp",
"env": {
"REDMINE_HOME": "/srv/redmine"
}
}
}
}
Precedence matters in fleets: an ambient per-kind variable such as REDMINE_DATA_DIR overrides an explicit --home for that kind. Use REDMINE_HOME or the per-kind variables for durable fleet relocation; treat --home as the weaker per-invocation lever.
Relocation is one-way. Unsetting REDMINE_HOME does not move files back to platform defaults, and doctor cannot find credentials left under a former root. Move the files manually before unsetting relocation variables.
Existing installs keep working because the platform-default rung matches the legacy layout. On the first auth write, stored secrets leave config.toml and are consolidated into credentials.toml under the data directory. Run redmine-pp-cli doctor --fail-on warn to check path and credential-location warnings in automation.
Commands
attachments
Status: Beta, Availability: 1.3
redmine-pp-cli attachments delete - Delete attachmentredmine-pp-cli attachments download-file - Undocumented: This operation is not listed in the official documentation.redmine-pp-cli attachments download-thumbnail - Undocumented: This operation is not listed in the official documentation.redmine-pp-cli attachments get - Show attachmentredmine-pp-cli attachments update - Update attachment
custom-fields-json
Manage custom fields json
redmine-pp-cli custom-fields-json - List custom fields
enumerations
Status: Alpha, Availability: 2.2
redmine-pp-cli enumerations get-document-categories - List document categoriesredmine-pp-cli enumerations get-issue-priorities - List issue prioritiesredmine-pp-cli enumerations get-time-entry-activities - List time entry activities
groups
Status: Alpha, Availability: 2.1
redmine-pp-cli groups delete - Delete groupredmine-pp-cli groups get - Show groupredmine-pp-cli groups update - Update group
groups-json
Manage groups json
redmine-pp-cli groups-json create-group - Create groupredmine-pp-cli groups-json get-groups - List groups
issue-categories
Status: Alpha, Availability: 1.3
redmine-pp-cli issue-categories delete-issue-category - Delete issue categoryredmine-pp-cli issue-categories get-issue-category - Show issue categoryredmine-pp-cli issue-categories update-issue-category - Update issue category
issue-statuses-json
Manage issue statuses json
redmine-pp-cli issue-statuses-json - List issue statuses
issues
Status: Stable, Availability: 1.0
redmine-pp-cli issues delete - Delete issueredmine-pp-cli issues get - Show issueredmine-pp-cli issues update - Update issue
issues-json
Manage issues json
redmine-pp-cli issues-json create-issue - Create issueredmine-pp-cli issues-json get-issues - List issues
journals
Status: Alpha, Availability: 5.0
redmine-pp-cli journals <journal_id> - The journal is deleted when it is updated with empty notes and has no property changes (details).
memberships
Manage memberships
redmine-pp-cli memberships delete - Delete membershipredmine-pp-cli memberships get - Show membershipredmine-pp-cli memberships update - Warning: sending an empty role_ids returns 422 but still destroys the membership — role assignments are saved immediately and a member left without roles is removed.
my
Manage my
redmine-pp-cli my get-account - Show my accountredmine-pp-cli my update-account - Requests authenticated via OAuth are rejected with 403, regardless of the token's scopes.
news
Status: Stable, Availability: 1.1
redmine-pp-cli news delete - Delete newsredmine-pp-cli news get - Show newsredmine-pp-cli news update - Update news
news-json
Manage news json
redmine-pp-cli news-json - List news
projects
Status: Stable, Availability: 1.0
redmine-pp-cli projects delete - Delete projectredmine-pp-cli projects get - Show projectredmine-pp-cli projects update - Update project
projects-json
Manage projects json
redmine-pp-cli projects-json create-project - Create projectredmine-pp-cli projects-json get-projects - List projects
queries-json
Manage queries json
redmine-pp-cli queries-json - List queries
relations
Manage relations
redmine-pp-cli relations delete-issue - Delete issue relationredmine-pp-cli relations get-issue - Show issue relation
roles
Status: Alpha, Availability: 1.4
redmine-pp-cli roles <role_id> - Show role
roles-json
Manage roles json
redmine-pp-cli roles-json - List roles
search-json
Manage search json
redmine-pp-cli search-json - Search
time-entries
Status: Stable, Availability: 1.1
redmine-pp-cli time-entries delete-time-entry - Delete time entryredmine-pp-cli time-entries get-time-entry - Show time entryredmine-pp-cli time-entries update-time-entry - Update time entry
time-entries-json
Manage time entries json
redmine-pp-cli time-entries-json create-time-entry - Create time entryredmine-pp-cli time-entries-json get-time-entries - List time entries
trackers-json
Manage trackers json
redmine-pp-cli trackers-json - List trackers
uploads-json
Manage uploads json
redmine-pp-cli uploads-json - Upload attachment file
users
Status: Stable, Availability: 1.1
redmine-pp-cli users delete - Delete userredmine-pp-cli users get - Show userredmine-pp-cli users get-current - Show current userredmine-pp-cli users update - Update user
users-json
Manage users json
redmine-pp-cli users-json create-user - Create userredmine-pp-cli users-json get-users - List users
versions
Status: Alpha, Availability: 1.3
redmine-pp-cli versions delete - Delete versionredmine-pp-cli versions get - Show versionredmine-pp-cli versions update - Update version
Self-learning loop
This CLI caches per-question discovery so repeat queries skip the walk and structurally similar queries get answered via entity substitution. The loop also self-captures: every invocation is journaled locally, and failed-flag corrections plus fresh teaches surface as candidates on the next recall for confirm/reject judgment. Agents call recall before discovery and fire teach & after answering. See the ## Automatic learning section in SKILL.md for the full protocol.
redmine-pp-cli recall <query> - Look up cached resources for a query before running discoveryredmine-pp-cli teach - Record a query -> resource mapping (silent on success, safe to background with &)redmine-pp-cli learnings list - Inspect taught rowsredmine-pp-cli learnings forget <query> - Undo a teachredmine-pp-cli learnings candidates - List auto-captured candidates awaiting confirm/rejectredmine-pp-cli learnings stats - Local loop metrics: recall hit rate, teach-to-reuse, playbook resolution, candidate countsredmine-pp-cli teach-pattern - Install a query/resource template up frontredmine-pp-cli teach-lookup - Add an entity mapping (e.g. country code, team alias) for pattern substitution
Pass --no-learn or set REDMINE_NO_LEARN=true to disable the loop for deterministic flows.
The local store's schema version stamp is one-way: once this version of redmine-pp-cli opens the database, older binaries refuse it with a version error — upgrade the binary rather than downgrading.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
redmine-pp-cli attachments get mock-value
# JSON for scripting and agents
redmine-pp-cli attachments get mock-value --json
# Filter to specific fields
redmine-pp-cli attachments get mock-value --json --select attachment
# Dry run — show the request without sending
redmine-pp-cli attachments get mock-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
redmine-pp-cli attachments get mock-value --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select <field>[,<field>...] returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and add --ignore-missing to delete retries when a no-op success is acceptable
- Explicit confirmation -
--agent does not imply --yes; pass --yes separately only after the target, arguments, and side effects are clear
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Freshness
This CLI owns bounded freshness for registered store-backed read command paths. In --data-source auto mode, covered commands check the local SQLite store before serving results; stale or missing resources trigger a bounded refresh, and refresh failures fall back to the existing local data with a warning. --data-source local never refreshes, and --data-source live reads the API without mutating the local store.
Set REDMINE_NO_AUTO_REFRESH=1 to disable the pre-read freshness hook while preserving the selected data source.
Covered command paths:
redmine-pp-cli custom-fields-jsonredmine-pp-cli custom-fields-json getredmine-pp-cli custom-fields-json listredmine-pp-cli custom-fields-json searchredmine-pp-cli enumerationsredmine-pp-cli enumerations getredmine-pp-cli enumerations listredmine-pp-cli enumerations searchredmine-pp-cli enumerations-issue-priorities-jsonredmine-pp-cli enumerations-issue-priorities-json getredmine-pp-cli enumerations-issue-priorities-json listredmine-pp-cli enumerations-issue-priorities-json searchredmine-pp-cli enumerations-time-entry-activities-jsonredmine-pp-cli enumerations-time-entry-activities-json getredmine-pp-cli enumerations-time-entry-activities-json listredmine-pp-cli enumerations-time-entry-activities-json searchredmine-pp-cli groups-jsonredmine-pp-cli groups-json getredmine-pp-cli groups-json listredmine-pp-cli groups-json searchredmine-pp-cli issue-statuses-jsonredmine-pp-cli issue-statuses-json getredmine-pp-cli issue-statuses-json listredmine-pp-cli issue-statuses-json searchredmine-pp-cli issues-jsonredmine-pp-cli issues-json getredmine-pp-cli issues-json listredmine-pp-cli issues-json searchredmine-pp-cli memberships-jsonredmine-pp-cli memberships-json getredmine-pp-cli memberships-json listredmine-pp-cli memberships-json searchredmine-pp-cli news-jsonredmine-pp-cli news-json getredmine-pp-cli news-json listredmine-pp-cli news-json searchredmine-pp-cli projects-jsonredmine-pp-cli projects-json getredmine-pp-cli projects-json listredmine-pp-cli projects-json searchredmine-pp-cli queries-jsonredmine-pp-cli queries-json getredmine-pp-cli queries-json listredmine-pp-cli queries-json searchredmine-pp-cli roles-jsonredmine-pp-cli roles-json getredmine-pp-cli roles-json listredmine-pp-cli roles-json searchredmine-pp-cli search-jsonredmine-pp-cli search-json getredmine-pp-cli search-json listredmine-pp-cli search-json searchredmine-pp-cli time-entries-jsonredmine-pp-cli time-entries-json getredmine-pp-cli time-entries-json listredmine-pp-cli time-entries-json searchredmine-pp-cli trackers-jsonredmine-pp-cli trackers-json getredmine-pp-cli trackers-json listredmine-pp-cli trackers-json searchredmine-pp-cli users-jsonredmine-pp-cli users-json getredmine-pp-cli users-json listredmine-pp-cli users-json search
JSON outputs that use the generated provenance envelope include freshness metadata at meta.freshness. This metadata describes the freshness decision for the covered command path; it does not claim full historical backfill or API-specific enrichment.
Runtime Endpoint
This CLI resolves endpoint placeholders at runtime, so one installed binary can target different tenants or API versions without regeneration.
Endpoint environment variables:
REDMINE_PROJECT_ID resolves {project_id}
Base URL: http://redmine:3000
Health Check
redmine-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Run redmine-pp-cli doctor to see the resolved config, data, state, and cache directories. The platform-default config path is ~/.config/redmine-pp-cli/config.toml; --home, REDMINE_HOME, and per-kind env vars can relocate it.
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
REDMINE_PROJECT_ID | endpoint | Yes | |
REDMINE_API_KEY | per_call | Yes | Set to your API credential. |
agentcookie (optional)
If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, redmine-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.
Troubleshooting
Authentication errors (exit code 4)
- Run
redmine-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $REDMINE_API_KEY
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- doctor reports 'connection refused' or a timeout — Confirm REDMINE_URL points at a reachable instance (e.g. http://redmine:3000 inside this devcontainer, http://localhost:3001 from the host browser) and that the Redmine container is healthy.
- 401 Unauthorized on every command — Confirm REDMINE_API_KEY is set and REST API access is enabled on the instance (Administration > Settings > API > 'Enable REST web service').
- issues-json create-issue fails with 'tracker_id is invalid' or similar — Run redmine-pp-cli trackers-json (or issue-statuses-json / enumerations get-issue-priorities) to get valid IDs for this instance — trackers, statuses, and priorities are configured per-instance and IDs are not portable across Redmine installs.
- roadmap burndown, issues cycle-time, or workload undercounts closed issues — The default 'sync' only pulls open issues (Redmine's own API default). Re-sync with '--resource-param issues-json:status_id=*' to include closed issues in the local mirror before running these commands.
- roadmap burndown or workload returns empty for a project that has data — Run sync first (or re-run it) — these commands read only from the local mirror, not live from the API.
HTTP Transport
This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls.
TLS certificates are verified by default. For a trusted development or self-signed endpoint only, pass --insecure for one invocation, set REDMINE_SKIP_TLS_VERIFY=true for the current environment, or set skip_tls_verify = true in the config file for a persistent override.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press