JiraCLI 是一个用于 Atlassian Jira 的交互式命令行工具，可以在一定程度上帮助你减少对 Jira UI 的依赖。该工具可能无法完成所有操作，但它包含了改善你日常工作流程所需的所有基本功能。 该工具的初衷是让问题的搜索和导航尽可能简单直接。然而，在[像你这样的杰出支持者](#support-the-project)的帮助下，我们不断发展，现在该工具已包含所有必要的功能，如问题创建、克隆、链接、工单状态转换等等。 ## 支持的平台 | 平台 | | | :------------- | :----------: | | **Jira** | | ## 安装 `jira-cli` 已作为打包好的可执行文件提供，可从 [发布页面](https://github.com/ankitpokhrel/jira-cli/releases) 下载，适用于 Linux、macOS 和 Windows。 你可以使用 Docker 快速试用 `jira-cli`。 ``` docker run -it --rm ghcr.io/ankitpokhrel/jira-cli:latest ``` 关于其他安装方式，如 `Homebrew`、`Nix` 等，请参考 [安装指南](https://github.com/ankitpokhrel/jira-cli/wiki/Installation)。 ## 快速开始 #### 云服务器 1. [获取 Jira API token](https://id.atlassian.com/manage-profile/security/api-tokens) 并将其作为 `JIRA_API_TOKEN` 变量导出到你的 shell 中。将其添加到你的 shell 配置文件中（例如 `$HOME/.bashrc`），以便该变量始终可用。或者，你也可以使用 `.netrc` 文件或 `keychain` 来设置 token。在[这里](https://github.com/ankitpokhrel/jira-cli/discussions/356)了解更多。 2. 运行 `jira init`，选择安装类型为 `Cloud`，并提供所需的详细信息，以生成该工具所需的配置文件。 #### 本地部署 1. 导出所需的环境变量： - 如果你使用的是基本认证，请将你登录 Jira 的 `password` 作为 `JIRA_API_TOKEN` 变量导出。 - 如果你使用的是个人访问令牌，请从你的 jira 个人资料中获取 `token` 并将其作为 `JIRA_API_TOKEN` 变量导出。此外，还需将 `JIRA_AUTH_TYPE` 环境变量设置为 `bearer`。 - 将这些环境变量添加到你的 shell 配置文件中（例如 `$HOME/.bashrc`），以便它们始终可用。 - 或者，你也可以使用 `.netrc` 文件或 `keychain` 来设置 token。在[这里](https://github.com/ankitpokhrel/jira-cli/discussions/356)了解更多。 2. 运行 `jira init`，选择安装类型为 `Local`，并提供所需的详细信息，以生成该工具所需的配置文件。 - 本地部署最常用的认证类型是 `basic`。如果你使用的是 jira 登录凭据（用户名和密码），请选择 `basic` 认证类型。 - 如果你想使用 `mtls`（客户端证书），请选择认证类型 `mtls` 并提供 CA 证书、客户端密钥和客户端证书。 请参阅 [常见问题解答](https://github.com/ankitpokhrel/jira-cli/discussions/categories/faqs)。 #### 认证类型 该工具支持 `basic`、`bearer`（个人访问令牌）和 `mtls`（客户端证书）认证类型。默认使用基本认证。 * 如果你想使用 PAT，需要将 `JIRA_AUTH_TYPE` 设置为 `bearer`。 * 如果你想使用 `mtls`，请运行 `jira init`。选择安装类型为 `Local`，然后选择认证类型为 `mtls`。 * 如果设置了 `JIRA_API_TOKEN` 变量，它将与 `mtls` 一起使用。 #### Shell 补全 请查看 `jira completion --help` 以获取有关设置 bash/zsh shell 补全的更多信息。 #### 多项目 你可以使用 `--config/-c` 标志加载特定的配置文件，或者通过设置 `JIRA_CONFIG_FILE` 环境变量来指定文件的位置。 ``` $ JIRA_CONFIG_FILE=./local_jira_config.yaml jira issue list // Or, you can use `--config/-c` flag $ jira issue list -c ./local_jira_config.yaml ``` ## 使用方法 该工具目前配备了问题、史诗 和冲刺 浏览器。相关标志符合 [POSIX 标准](https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html)。 你可以以任意顺序组合可用的标志来创建独特的查询。例如，下面的命令将为你列出本月创建的、状态为 `To Do`、分配给你且带有 `backend` 标签的高优先级问题。 ``` jira issue list -yHigh -s"To Do" --created month -lbackend -a$(jira me) ``` ### 导航 列表默认以交互式 UI 显示。 - 使用方向键或 `j, k, h, l` 字符在列表中导航。 - 使用 `g` 和 `G` 分别快速导航到顶部和底部。 - 使用 `CTRL + f` 向下滚动一页。 - 使用 `CTRL + b` 向上滚动一页。 - 按 `v` 查看所选问题的详情。 - 按 `m` 转换所选问题的状态。 - 按 `CTRL + r` 或 `F5` 刷新问题列表。 - 按 `ENTER` 在浏览器中打开所选问题。 - 按 `c` 将问题 URL 复制到系统剪贴板。在 Linux 上这需要 `xclip` / `xsel`。 - 按 `CTRL + k` 将问题 key 复制到系统剪贴板。 - 在浏览器视图中，按 `w` 或 `TAB` 可在侧边栏和内容屏幕之间切换焦点。 - 按 `q` / `ESC` / `CTRL + c` 退出。 - 按 `?` 打开帮助窗口。 ### 资源 - [常见问题解答](https://github.com/ankitpokhrel/jira-cli/discussions/categories/faqs) - [简介与动机](https://medium.com/@ankitpokhrel/introducing-jira-cli-the-missing-command-line-tool-for-atlassian-jira-fe44982cc1de) - [JiraCLI 入门](https://www.mslinn.com/blog/2022/08/12/jiracli.html) ## 命令 ### 问题 问题默认以交互式表格视图显示。你可以使用 `--plain` 标志以纯文本视图输出结果。 #### 列表 `list` 命令允许你搜索和导航问题。问题默认按 `created` 字段降序排列。 ``` # 列出最近的问题 $ jira issue list # 列出最近 7 天创建的问题 $ jira issue list --created -7d # 列出状态为 "To Do" 的问题 $ jira issue list -s"To Do" # 以纯文本模式列出最近的问题 $ jira issue list --plain # 以原始 JSON 格式列出最近的问题 $ jira issue list --raw # 以 csv 格式列出最近的问题 $ jira issue list --csv # 按照 UI 中显示的顺序列出问题 $ jira issue list --order-by rank --reverse # 你可以使用 `--jql/-q` 选项在给定的项目上下文中执行原始 JQL。 # 例如，以下命令将列出当前项目中摘要 # 包含单词 cli 的问题。 $ jira issue list -q "summary ~ cli" ``` 请查看下方更多的示例/用例。

列出我正在关注的问题

``` jira issue list -w ```

列出分配给我的问题

``` jira issue list -a$(jira me) ```

列出分配给某用户且由另一用户报告的问题

``` jira issue list -a"User A" -r"User B" ```

列出分配给我的、高优先级且处于开放状态的问题

``` jira issue list -a$(jira me) -yHigh -sopen ```

列出未分配给任何人且本周创建的问题

``` jira issue list -ax --created week ```

列出解决方案为“won't do”的问题

``` jira issue list -R"Won't do" ```

列出状态未完成、创建于 6 个月前且已分配给某人的问题

``` # 波浪号 (~) 用作非运算符 jira issue list -s~Done --created-before -24w -a~x ```

列出创建于 1 小时内且在过去 30 分钟内更新过的问题 :stopwatch:

``` jira issue list --created -1h --updated -30m ```

获取高优先级、进行中、本月创建且带有指定标签的问题 :fire:

``` jira issue list -yHigh -s"In Progress" --created month -lbackend -l"high-prio" ```

等等，我今天早些时候打开的那个工单是什么来着？:tired_face:

``` jira issue list --history ```

我在当前面板上报告过的第一个问题是什么？:thinking:

``` jira issue list -r$(jira me) --reverse ```

我在当前面板上修复过的第一个 Bug 是什么？:beetle:

``` jira issue list -a$(jira me) -tBug sDone -rFixed --reverse ```

我本周报告了哪些问题？:man_shrugging:

``` jira issue list -r$(jira me) --created week ```

我在项目 XYZ 中是否关注了任何工单？:monocle_face:

``` jira issue list -w -pXYZ ```

#### 创建 `create` 命令允许你创建一个问题。 ``` # 使用交互式提示创建问题 $ jira issue create # 传递必需参数并使用 --no-input 选项跳过提示 $ jira issue create -tBug -s"New Bug" -yHigh -lbug -lurgent -b"Bug description" --fix-version v2.0 --no-input ``` 要在创建时将问题附加到 Epic，你可以使用 `-P/--parent` 字段。我们称之为 parent，是因为 Epic 的语义在 `next-gen` 项目中已发生改变。 ``` # 创建类型为 Story 的问题并将其附加到键为 EPIC-42 的 epic $ jira issue create -tStory -s"Epic during creation" -PEPIC-42 ```  你可以使用 `--custom` 标志在创建问题时设置自定义字段。详情请参阅[这篇文章](https://github.com/ankitpokhrel/jira-cli/discussions/346)。 该命令支持 [Github 风格](https://github.github.com/gfm/)和 [Jira 风格](https://jira.atlassian.com/secure/WikiRendererHelpAction.jspa?section=all)的 Markdown 来编写描述。你可以使用 `--template` 标志加载预定义的模板。 ``` # 从模板文件加载描述 $ jira issue create --template /path/to/template.tmpl # 从标准输入获取描述 $ jira issue create --template - # 或者，使用管道直接从标准输入读取输入 $ echo "Description from stdin" | jira issue create -s"Summary" -tTask ```  #### 编辑 `edit` 命令允许你编辑一个问题。 ``` $ jira issue edit ISSUE-1 # 在已配置的项目中编辑问题 $ jira issue edit ISSUE-1 -s"New Bug" -yHigh -lbug -lurgent -CBackend -b"Bug description" # 使用 --no-input 选项禁用交互式提示 $ jira issue edit ISSUE-1 -s"New updated summary" --no-input # 使用减号 (-) 移除 label、component 或 fixVersion # 例如，编辑问题以 # - 移除 label p2、component FE、fixVersion v1.0 # - 添加 label p1、component BE、fixVersion v2.0 $ jira issue edit ISSUE-1 --label -p2 --label p1 --component -FE --component BE --fix-version -v1.0 --fix-version v2.0 ``` #### 分配 `assign` 命令允许你将用户分配给问题。 ``` # 使用交互式提示将用户分配给问题 $ jira issue assign # 传递必需参数以跳过提示 $ jira issue assign ISSUE-1 "Jon Doe" # 分配给自己 $ jira issue assign ISSUE-1 $(jira me) # 如果关键字后缀返回多个条目，将提示进行选择 $ jira issue assign ISSUE-1 suffix # 分配给默认被分配人 $ jira issue assign ISSUE-1 default # 取消分配 $ jira issue assign ISSUE-1 x ```  #### 移动/转换 `move` 命令允许你将问题从一种状态转换为另一种状态。 ``` # 使用交互式提示移动问题 $ jira issue move # 传递必需参数以跳过提示 $ jira issue move ISSUE-1 "In Progress" ```  如果你的工作流允许在移动问题时添加评论、解决方案或受让人，你可以如下所示进行操作。请参阅[此文档](https://confluence.atlassian.com/jirakb/how-to-add-a-comment-during-a-transition-779160682.html)了解如何设置你的工作流以允许这些字段。 ``` # 移动问题并添加评论 $ jira issue move ISSUE-1 "In Progress" --comment "Started working on it" # 在移动问题时将 resolution 设置为 fixed 并分配给自己 $ jira issue move ISSUE-1 Done -RFixed -a$(jira me) ``` 要从 TUI 转换选中的问题，请按 `m`。 #### 查看 `view` 命令允许你在终端中查看问题详情。Atlassian 文档会被粗略地转换为 Markdown 并在终端中精美地显示出来。 该命令默认使用 `less` 作为分页器。要设置你自己的分页器，请参阅 https://github.com/ankitpokhrel/jira-cli/discussions/569。 ``` $ jira issue view ISSUE-1 ```  查看屏幕将在描述之后显示链接的问题和最新的评论。请注意，如果你因为某种原因在一个工单中有超过 5k 条评论，显示的评论可能不是最新的。 ``` # 查看问题时显示最近 5 条评论 $ jira issue view ISSUE-1 --comments 5 ``` #### 链接 `link` 命令允许你链接两个问题。 ``` # 使用交互式提示链接问题 $ jira issue link # 传递必需参数以跳过提示 $ jira issue link ISSUE-1 ISSUE-2 Blocks ``` ##### 远程链接 `remote` 命令允许你向问题添加远程 Web 链接。 ``` # 使用交互式提示添加远程 Web 链接 $ jira issue link remote # 传递必需参数以跳过提示 $ jira issue link remote ISSUE-1 https://example.com "Example text" ``` #### 取消链接 `unlink` 命令允许你取消两个已链接问题的链接。 ``` # 使用交互式提示取消链接问题 $ jira issue unlink # 传递必需参数以跳过提示 $ jira issue unlink ISSUE-1 ISSUE-2 ``` #### 克隆 `clone` 命令允许你克隆一个问题。你可以在克隆问题时更新摘要、优先级、受让人、标签和组件等字段。该命令还允许你使用 `--replace/-H` 选项替换摘要和描述中的部分字符串（区分大小写）。 ``` # 克隆问题 $ jira issue clone ISSUE-1 # 克隆问题并修改摘要、优先级和被分配人 $ jira issue clone ISSUE-1 -s"Modified summary" -yHigh -a$(jira me) # 克隆问题并替换摘要和描述中的文本 $ jira issue clone ISSUE-1 -H"find me:replace with me" ``` #### 删除 `delete` 命令允许你删除一个问题。 ``` # 使用交互式提示删除问题 $ jira issue delete # 传递必需参数以跳过提示 $ jira issue delete ISSUE-1 # 删除任务及其所有子任务 $ jira issue delete ISSUE-1 --cascade ``` #### 评论 `comment` 命令提供了一系列子命令来管理问题评论。 ##### 添加 `add` 命令允许你向问题添加评论。该命令支持 [Github 风格](https://github.github.com/gfm/)和 [Jira 风格](https://jira.atlassian.com/secure/WikiRendererHelpAction.jspa?section=all)的 Markdown 来编写评论。你可以使用 `--template` 标志加载预定义的模板。 ``` # 使用交互式提示添加评论 $ jira issue comment add # 传递必需参数以跳过提示 $ jira issue comment add ISSUE-1 "My comment body" # 与上述相同，但作为内部评论 $ jira issue comment add ISSUE-1 "My comment body" --internal # 从模板文件加载评论 $ jira issue comment add ISSUE-1 --template /path/to/template.tmpl # 从标准输入获取评论 $ jira issue comment add ISSUE-1 --template - # 或者，使用管道直接从标准输入读取输入 $ echo "Comment from stdin" | jira issue comment add ISSUE-1 ``` ``` jira issue comment add ISSUE-42 "comment body positional" --template - <<'EOF' comment body template EOF ``` #### 工作日志 `worklog` 命令提供了一系列子命令来管理工作日志（时间日志）。 ##### 添加 `add` 命令允许你向问题添加工作日志。该命令支持为工作日志评论使用 Markdown。 ``` # 使用交互式提示添加工作日志 $ jira issue worklog add # 传递必需参数并使用 --no-input 跳过提示 $ jira issue worklog add ISSUE-1 "2d 3h 30m" --no-input # 添加工作日志时可以使用 --comment 标志添加评论 $ jira issue worklog add ISSUE-1 "10m" --comment "This is a comment" --no-input ``` ### 史诗 史诗默认以浏览器视图显示。你可以使用 `--table` 标志以表格视图输出结果。 在查看史诗问题时，你可以使用问题命令的所有可用过滤器。 请参阅[用法](#navigation)以了解更多关于 UI 交互的信息。 #### 列表 你可以在此处使用 `issue list` 命令支持的所有标志，但问题类型除外。 ``` # 列出 epics $ jira epic list # 以表格视图列出 epics $ jira epic list --table # 列出由我报告且处于打开状态的 epics $ jira epic list -r$(jira me) -sOpen # 列出 epic 中的问题 $ jira epic list KEY-1 # 列出 epic KEY-1 中所有未分配且优先级高的问题 $ jira epic list KEY-1 -ax -yHigh # 列出高优先级 epics $ jira epic list KEY-1 -yHigh # 按排名升序 (ASC) 列出 epic 问题 $ jira epic list KEY-1 --order-by rank --reverse ``` #### 创建 创建史诗与创建问题相同，但你还需要提供一个史诗名称。 ``` # 使用交互式提示创建问题 $ jira epic create # 传递必需参数以跳过提示，或使用 --no-input 标志跳过非强制参数的提示 $ jira epic create -n"Epic epic" -s"Everything" -yHigh -lbug -lurgent -b"Epic description" ``` #### 添加 `add` 命令允许你将问题添加到史诗中。你一次最多可以添加 50 个问题到史诗中。 ``` # 使用交互式提示将问题添加到 epic $ jira epic add # 传递必需参数以跳过提示 $ jira epic add EPIC-KEY ISSUE-1 ISSUE-2 ``` #### 移除 `remove` 命令允许你从史诗中移除问题。一次最多可以从史诗中移除 50 个问题。 ``` # 使用交互式提示从 epic 中移除问题 $ jira epic remove # 传递必需参数以跳过提示 $ jira epic remove ISSUE-1 ISSUE-2 ``` ### 冲刺 冲刺默认以浏览器视图显示。你可以使用 `--table` 标志以表格视图输出结果。 在查看冲刺问题时，你可以使用问题命令的所有可用过滤器。该工具仅显示最近的 25 个冲刺。 请参阅[用法](#navigation)以了解更多关于 UI 交互的信息。 #### 列表 你可以使用 `issue list` 命令支持的所有标志来过滤冲刺中的问题。 ``` # 以浏览器视图列出 sprints $ jira sprint list # 以表格视图列出 sprints $ jira sprint list --table # 列出当前活跃 sprint 中的问题 $ jira sprint list --current # 列出当前活跃 sprint 中分配给我的问题 $ jira sprint list --current -a$(jira me) # 列出上一个 sprint 中的问题 $ jira sprint list --prev # 列出下一个计划 sprint 中的问题 $ jira sprint list --next # 列出未来和活跃的 sprints $ jira sprint list --state future,active # 列出特定 sprint 中的问题。你可以在此处使用 issue list 命令支持的所有标志。 # 要获取 sprint id，请使用 `jira sprint list` 或 `jira sprint list --table` $ jira sprint list SPRINT_ID # 列出 sprint 中分配给我的高优先级问题 $ jira sprint list SPRINT_ID -yHigh -a$(jira me) # 按排名升序 (ASC) 列出 sprint 问题 $ jira sprint list SPRINT_ID --order-by rank --reverse ``` #### 添加 `add` 命令允许你将问题添加到冲刺中。你一次最多可以添加 50 个问题到冲刺中。 ``` # 使用交互式提示将问题添加到 sprint $ jira sprint add # 传递必需参数以跳过提示 $ jira sprint add SPRINT_ID ISSUE-1 ISSUE-2 ``` ### 发布版本 与发布版本（项目版本）进行交互。 请确保你的实例上已[启用该功能](https://support.atlassian.com/jira-software-cloud/docs/enable-releases-and-versions/)。 #### 列表 ``` # 列出默认项目的 releases $ jira release list # 列出特定项目的 releases $ jira release list --project 1000 $ jira release list --project KEY ``` ### 其他命令

导航到项目

``` jira open ```

导航到问题

``` jira open KEY-1 ```

列出你有权访问的所有项目

``` jira project list ```

列出项目中的所有面板

``` jira board list ```

## 脚本 很多时候，你可能希望使用命令的输出来完成一些很酷的事情。然而，默认的交互式 UI 可能无法满足这一需求。 该工具提供了 `--plain` 标志，它可以以简单的布局显示结果，然后可以在 shell 脚本中进行处理。 下面列出了一些示例脚本。

本月每天创建的工单数

``` #!/usr/bin/env bash tickets=$(jira issue list --created month --plain --columns created --no-headers | awk '{print $2}' | awk -F'-' '{print $3}' | sort -n | uniq -c) echo "${tickets}" | while IFS=$'\t' read -r line; do day=$(echo "${line}" | awk '{print $2}') count=$(echo "${line}" | awk '{print $1}') printf "Day #%s: %s\n" "${day}" "${count}" done # 输出 Day #01: 19 Day #02: 10 Day #03: 21 ... ```

每个冲刺的工单数

``` #!/usr/bin/env bash sprints=$(jira sprint list --table --plain --columns id,name --no-headers) echo "${sprints}" | while IFS=$'\t' read -r id name; do count=$(jira sprint list "${id}" --plain --no-headers 2>/dev/null | wc -l) printf "%10s: %3d\n" "${name}" $((count)) done # 输出 Sprint 3: 55 Sprint 2: 40 Sprint 1: 30 ... ```

每个冲刺的唯一受让人数量

``` #!/usr/bin/env bash sprints=$(jira sprint list --table --plain --columns id,name --no-headers) echo "${sprints}" | while IFS=$'\t' read -r id name; do count=$(jira sprint list "${id}" --plain --columns assignee --no-headers 2>/dev/null | awk '{print $2}' | awk NF | sort -n | uniq | wc -l) printf "%10s: %3d\n" "${name}" $((count)) done # 输出 Sprint 3: 5 Sprint 2: 4 Sprint 1: 3 ```

## 已知问题 1. 目前并非所有 [Atlassian 节点](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/#nodes)都能被正确转换，这有时会导致格式问题。 ## 功能请求 请在 `ideas` 分类中[开启一个讨论](https://github.com/ankitpokhrel/jira-cli/discussions/categories/ideas)来提出功能建议。 ##### 这些请求通常如何确定优先级？ - 那些实现简单、不需要太多脑力、即使我很懒也能完成的功能会优先被采纳。 - 如果该功能是我在日常工作中也缺失的，它可能会被优先处理。 - 其余功能将根据特定功能的[投票数](https://github.com/ankitpokhrel/jira-cli/discussions/categories/ideas)来决定是否被采纳。 ## 开发 1. 克隆仓库。 git clone git@github.com:ankitpokhrel/jira-cli.git 2. 可选：如果你想在本地运行 Jira 实例，可以使用以下 make 命令。 试用许可证密钥可以从 [atlassian admin](https://my.atlassian.com) 的 "Licenses" 部分生成。 make jira.server 3. 进行更改，构建二进制文件，并测试你的更改。 make deps install 4. 在提交 PR 之前，在本地运行 CI 步骤。 make ci ## 支持项目 非常感谢你的建议和反馈。请随时[开始一个讨论](https://github.com/ankitpokhrel/jira-cli/discussions)或[创建一个 issue](https://github.com/ankitpokhrel/jira-cli/issues/new)来分享你使用该工具的体验或讨论功能/问题。 如果你认为这个工具有用，为你节省了大量工作，并让你睡得更安稳，那么请考虑通过以下任何方式支持该项目： - [给仓库点 Star](https://github.com/ankitpokhrel/jira-cli/stargazers)。 - 在社交媒体上或与朋友分享该项目，传播出去。 - [报告 Bug](https://github.com/ankitpokhrel/jira-cli/issues/new/choose)或[提出解决方案](https://github.com/ankitpokhrel/jira-cli/issues)。 - [捐赠少量金额](https://opencollective.com/jira-cli#backers)。

标签：API客户端, EVTX分析, Go语言, Issue跟踪, Jira, Linux 内核安全, 交互式命令行, 任务管理, 命令行界面, 威胁情报, 开发者工具, 敏捷开发, 日志审计, 程序破解, 终端工具, 网络调试, 自动化, 请求拦截, 项目管理