Redmine CLI

Redmine CLI

A CLI for the Redmine REST API. Use redmine <command> --help for detailed flags and examples — this skill only covers what --help cannot tell you.

Available Commands

Only these top-level commands exist. Do NOT invent subcommands that aren't listed here — run redmine <command> --help to discover subcommands.

Setup

If the redmine command is not found, install it:

curl -fsSL https://raw.githubusercontent.com/aarondpn/redmine-cli/main/install.sh | bash

Then run redmine auth login for interactive configuration. Use redmine config to verify an existing setup.

Critical Rules

• Always use -o json when you need to parse output programmatically. JSON goes to stdout only; stderr is separate.
• Use --limit 0 to fetch ALL results. The default limit is 100.
• All name-accepting flags (--project, --tracker, --status, --priority, --assignee, --category, --version, --activity) resolve human-readable names automatically. You don't need to look up IDs first.
• --assignee me refers to the current API user.
• --status "*" shows all issues regardless of status (default is open).

When Something Doesn't Work: Stop and Use --help

Do NOT guess, loop, or retry with invented flags/subcommands. If a command fails or you're unsure about the correct syntax:

1. Run redmine <command> --help (or redmine <command> <subcommand> --help) to see the actual available options, flags, and subcommands.
2. Read the help output carefully — it is authoritative and always up to date. Trust it over your own assumptions.
3. Never invent flags or subcommands that aren't shown in --help. If you think an option should exist but it doesn't appear in the help, it doesn't exist.
4. Do not loop — if the same command fails twice, stop and re-read the help output. Do not keep retrying with slight variations hoping one will work.
5. Parse output with -o json and standard JSON tools (jq) — never use Python scripts, awk hacks, or regex to parse CLI output. The CLI's JSON output is well-structured; use it.
6. Ask the user if the help output doesn't clarify things — that's better than spiraling through failed attempts.

Permission Gotcha: Users & Groups

Resolving users and groups by name requires admin privileges. If you get a permission error:

• Do NOT retry with the same name
• Use me for the current user
• To discover user IDs without admin access, extract them from other sources:
  • redmine issues list --project <project> -o json — the assigned_to and author fields contain user IDs and names
  • redmine memberships list --project <project> -o json — lists all project members with their IDs
  • redmine issues get <id> --journals -o json — journal entries contain user references

Workflow: Resolving Ambiguous Values

When a command needs a value from a fixed set (tracker, status, priority, category, version, assignee) and you're not sure of the exact name:

1. Query options first: redmine trackers list -o json, redmine statuses list -o json, etc.
2. Present choices to the user via AskUserQuestion with a formatted list
3. Use the confirmed value in the command

For users/groups, if the list endpoint fails with a permission error, use the workarounds from the section above instead.

After Creating Resources

When you create an issue, project, user, or other resource, the CLI returns the new ID. Offer the user a clickable URL so they can open it in the browser:

• Issues: redmine issues open <id> opens the issue directly. You can also provide the URL: <server>/issues/<id>
• Projects: <server>/projects/<identifier>
• Users: <server>/users/<id>
• Time entries: <server>/time_entries/<id>/edit

Get the server URL from redmine config (or from the JSON output's hints). Always mention the URL or the open command after a successful create so the user can quickly navigate to the new resource.

Attachments: Always Download and Inspect Them

Issues often carry attachments (screenshots, diagrams, logs, PDFs) that contain information not present in the text. Whenever an issue has attachments, download them and inspect their contents before answering - especially images, which frequently hold the actual error, mockup, or detail the ticket is about.

1. Discover attachment IDs: redmine issues get <id> --attachments lists each attachment's id, filename, size, and content_type. With -o json the issue's attachments[] array is included in the output.
2. Download one file: redmine attachments download <att-id> -d <dir> saves it under its real filename (or --path <file> for an exact path, --path - to stream to stdout). No curl, no manual API-key handling - it reuses the active profile's auth.
3. Download everything at once: redmine issues get <id> --download-attachments <dir> pulls every attachment of the issue into <dir> in one step.
4. Inspect metadata only (no download): redmine attachments get <att-id>.

After downloading an image, open/read it and use what it shows. Do not answer a question about a ticket with attachments without first looking at them.

Non-Obvious Behaviors

• redmine issues list defaults to --status open. Use --status closed, --status "*", or a specific status name.
• redmine issues get <id> --journals includes comments/history. Also available: --children, --relations, --attachments.
• redmine issues update only sends flags you explicitly pass — omitted flags are not changed.
• If --project is omitted, the configured default project is used (set via redmine auth login).
• Projects can accumulate hundreds of versions, most of them closed or locked. When you need a version for a new issue, time entry, or similar workflow, always start from redmine versions list --open so the shortlist stays small and you don't pick a version that can no longer accept work.
• Any date flag (--due-date, --date, --from, --to) accepts the literal keyword today as a shortcut for the current date.