redmine-cli

Redmine CLI

用于 Redmine REST API 的命令行工具。运行 redmine <command> --help 可查看详细标志和示例——本技能仅介绍 --help 无法说明的内容。

可用命令

仅存在以下顶层命令。请勿臆造此处未列出的子命令——运行 redmine <command> --help 以查看子命令。

命令	用途
issues	创建、列出、获取、更新、关闭、重新打开、分配、评论、删除、打开和浏览问题；管理关注者和关联关系（issues watchers …、issues relations …）。搜索问题时，请使用 search issues
attachments	使用当前配置文件的身份验证查看附件元数据（attachments get <id>）并下载附件文件（attachments download <id>）
queries	列出 Redmine 已保存的查询；通过 issues list --query / --query-id 重用
projects	列出、获取、创建、更新、归档、取消归档和删除项目；列出项目成员。列表和获取命令中的 --include 可显示跟踪器、模块、类别、自定义字段和工时记录活动（归档功能需要 Redmine 5.0+）。
time	记录、列出、获取、更新、删除工时记录并汇总工时
versions	创建、列出、获取、更新和删除项目版本（里程碑）
files	列出和上传项目级文件（发布工件）
memberships	列出、获取、创建、更新和删除项目成员关系
users	列出、获取、创建、更新和删除用户
my-account	获取和更新你自己的 Redmine 账户（无需管理员权限）
groups	列出、获取、创建、更新和删除群组；添加/移除用户
roles	列出和获取角色及其权限
categories	列出问题类别
trackers	列出和获取跟踪器
statuses	列出问题状态
custom-fields	列出和获取自定义字段定义（仅限管理员的端点）
search	搜索问题、维基、新闻、消息或浏览结果
auth	登录、注销、列出、切换和检查身份验证配置文件的状态
wiki	列出、获取、创建、更新和删除维基页面
api	发起原始的身份验证 API 请求
config	显示当前配置（服务、配置文件、默认项目）
update	将 CLI 更新到最新版本

设置

如果找不到 redmine 命令，请安装：

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

然后运行 redmine auth login 进行交互式配置。使用 redmine config 验证现有设置。

重要规则

• 使用 --jq（-q）提取字段——例如：redmine issues get 123 --jq '.status.name'。此功能内置（无需外部 jq），并且会启用 -o json。切勿使用 Python、awk 或正则表达式解析输出。如果不识别该标志，说明 CLI 版本过旧——请让用户运行 redmine update。
• 错误会输出到 stderr，并返回非零退出代码；失败时 stdout 为空。请检查退出代码——切勿将 stderr 合并到 stdout（2>&1），也不要丢弃 stderr（2>/dev/null）。错误代码 jq_failed 表示命令本身已成功，只是筛选器执行失败——不要重新运行写入操作（但如果 api -i 收到 4xx/5xx 响应，则请求失败）。
• 使用 --limit 0 获取所有结果。默认限制为 100。
• 检查附件：读取问题时，添加 --attachments，并在回答前查看该问题是否包含附件（见下文）。
• 所有接受名称的标志（--project、--tracker、--status、--priority、--assignee、--category、--version、--activity）都会自动解析易读名称。不要预先查询 ID 或选项列表——只有名称无法解析时，才检查有效值（例如 redmine projects get <project> --include trackers,issue_categories），如果仍不明确，再询问用户。
• --assignee me 指当前 API 用户。
• --status "*" 显示所有状态的问题（默认值为 open）。

遇到问题时：停止操作并使用 --help

切勿猜测、循环尝试或使用编造的标志／子命令重试。 如果命令失败，或你不确定正确的语法：

1. 运行 redmine <command> --help（或 redmine <command> <subcommand> --help），查看实际可用的选项、标志和子命令。
2. 仔细阅读帮助输出——它是权威信息，并且始终保持最新。请以它为准，不要依赖自己的假设。
3. 切勿编造 --help 中未显示的标志或子命令。 如果你认为某个选项应该存在，但帮助中没有，它就不存在。
4. 不要循环尝试——如果同一条命令失败两次，就停止并重新阅读帮助输出。不要寄希望于稍微修改一下命令就能成功，然后不断重试。
5. 如果帮助输出未能澄清问题，请询问用户——这比陷入反复失败的尝试要好。

权限错误

• 切勿使用其他凭据重试（其他配置文件、环境变量中的 API 密钥、CI 设置或配置文件）。权限取决于用户的 Redmine 角色——请停止操作并询问用户。
• 用户名和组名会通过项目成员进行解析，因此无需管理员权限也能使用。

创建资源后

创建问题、项目、用户或其他资源时，CLI 会返回新 ID。请向用户提供可点击的 URL，方便他们在浏览器中打开：

• 问题：redmine issues open <id> 会直接打开该问题。你也可以提供 URL：<server>/issues/<id>
• 项目：<server>/projects/<identifier>
• 用户：<server>/users/<id>
• 时间条目：<server>/time_entries/<id>/edit

使用 redmine config --jq .server 获取服务器 URL。成功创建后，务必告知用户 URL 或 open 命令，方便他们快速访问新资源。

附件：务必下载并检查

问题通常附带附件（屏幕截图、示意图、日志、PDF），其中可能包含正文中没有的信息。只要问题有附件，就必须先下载并检查附件内容，再作答，尤其是图片，因为其中往往包含工单所涉及的实际错误、原型图或详细信息。

1. 查找附件 ID：redmine issues get <id> --attachments 会列出每个附件的 id、filename、filesize 和 content_type（JSON：.attachments[]）。不加 --attachments 时，问题输出不会显示这些信息。
2. 下载单个文件：redmine attachments download <att-id> -d <dir> 会将文件保存为其实际文件名（也可以使用 --path <file> 指定确切路径，或使用 --path - 将内容流式输出到 stdout）。不要使用 curl，也不要手动处理 API 密钥——它会复用当前配置文件的身份验证信息。
3. 一次性下载所有附件：redmine issues get <id> --download-attachments <dir> 会一步将该问题的所有附件下载到 <dir>。
4. 仅检查元数据（不下载）：redmine attachments get <att-id>。

下载图片后，请打开／读取图片并参考其中显示的内容。

不明显的行为

• redmine issues get <id> --journals 会包含评论／历史记录。
• redmine issues update 只会发送你明确传入的标志——未指定的标志不会更改。
• 如果省略 --project，则会使用已配置的默认项目（通过 redmine auth login 设置）。
• 项目可能积累数百个版本，其中大多数已关闭或锁定。为新问题、时间条目或类似工作流选择版本时，务必先运行 redmine versions list --open，以缩小候选范围，避免选中无法继续处理工作的版本。
• 所有日期标志（--due-date、--date、--from、--to）都接受字面关键字 today，作为当前日期的快捷方式。