Jira CLI

功能丰富的交互式 Jira 命令行工具

_{个人和企业赞助者提供的资金支持，可确保该工具持续开发。
如果你或你的公司依赖 JiraCLI，请考虑赞助此项目。}

JiraCLI 是一款适用于 Atlassian Jira 的交互式命令行工具，可帮助你在一定程度上避免使用 Jira UI。 该工具或许无法完成所有事情，但具备改善你日常 Jira 工作流所需的所有核心功能。

该工具最初旨在让问题搜索和导航尽可能简单。不过，在像你这样的杰出支持者的帮助下，我们不断完善，如今工具已包含问题创建、克隆、关联、工单状态转换等各种必要功能。

该工具深受 GitHub CLI 的启发

支持的平台

说明

由于数据性质不同，某些功能在 Jira Cloud 和本地部署之间可能略有差异。不过，我们已尽力让使用体验尽可能相似。

平台
Jira

_{SKILL.md ← 适用于 Agent}

JiraCLI 可与 Claude Code、Codex、OpenCode 等由大模型驱动的命令行工具，以及基于 shell 的自动化工具良好配合。

安装

jira-cli 可从 releases 页面下载适用于 Linux、macOS 和 Windows 的打包二进制文件。

你可以使用 Docker 快速试用 jira-cli。

docker run -it --rm ghcr.io/ankitpokhrel/jira-cli:latest

如需了解 Homebrew、Nix 等其他安装方式，请参阅安装指南。

入门

Cloud 服务

1. 获取 Jira API token，并将其导出到 shell 中，设为 JIRA_API_TOKEN 变量。将其添加到 shell 配置文件中，例如 $HOME/.bashrc，以便随时使用该 变量。或者，也可以使用 .netrc 文件或 keychain 设置 token。了解 更多信息，请点击此处。
2. 运行 jira init，选择安装类型 Cloud，并提供所需信息，以生成该工具所需的配置文件。

本地部署

1. 导出所需的环境变量：
   • 如果使用基本身份验证，请将你用于登录 Jira 的 password 导出为 JIRA_API_TOKEN 变量。
   • 如果使用个人访问令牌（PAT），请从 Jira 个人资料中获取 token，并将其导出为 JIRA_API_TOKEN 变量。此外，将环境变量 JIRA_AUTH_TYPE 设置为 bearer。
   • 将这些环境变量添加到 shell 配置文件中，例如 $HOME/.bashrc，以便始终可以使用它们。
   • 或者，你也可以使用 .netrc 文件或 keychain 来设置令牌。了解 更多信息请参阅这里。
2. 运行 jira init，将安装类型选择为 Local，并提供所需信息，以生成工具所需的配置文件。
   • 本地部署最常用的身份验证类型是 basic。如果使用 Jira 登录凭据 （用户名和密码），请选择 basic 身份验证类型。
   • 如果要使用 mtls（客户端证书），请选择身份验证类型 mtls，并提供 CA 证书、客户端密钥和客户端证书。

重要

如果本地部署的 Jira 使用的语言不是 English，则创建问题/史诗可能无法正常工作，因为较旧版本的 Jira API 不会返回未翻译的 issuetypes 名称。在这种情况下， 你需要在生成的配置中手动填写 epic.name、epic.link 和 issue.types.*.handle 字段， 以获得预期效果。

常见问题请参阅 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

# Alternatively, use the `--config/-c` flag
$ jira issue list -c ./local_jira_config.yaml

用法

此工具目前提供问题、史诗和冲刺浏览器。标志符合 POSIX 规范。 你可以按任意顺序组合可用标志，以创建独特的查询。例如，下面的命令会显示本月创建的高优先级问题， 这些问题的状态为 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 将问题键复制到系统剪贴板。
• 在浏览器视图中，按 w 或 TAB 在侧边栏和内容屏幕之间切换焦点。
• 按 q / ESC / CTRL + c 退出。
• 按 ? 打开帮助窗口。

资源

• 常见问题
• 简介与动机
• JiraCLI 入门指南

命令

问题

默认情况下，问题会以交互式表格视图显示。你可以使用 --plain 标志，以纯文本视图输出结果。

列出

list 命令可让你搜索和浏览问题。默认情况下，问题按 created 字段降序排列。

# List recent issues
$ jira issue list

# List issues created in last 7 days
$ jira issue list --created -7d

# List issues in status "To Do"
$ jira issue list -s"To Do"

# List recent issues in plain mode
$ jira issue list --plain

# List recent issues in raw JSON format
$ jira issue list --raw

# List recent issues in csv format
$ jira issue list --csv

# List issue in the same order as you see in the UI
$ jira issue list --order-by rank --reverse

# You can execute raw JQL within a given project context using `--jql/-q` option.
# For instance, the following command will list issues in the current project whose
# summary has a word 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

jira issue list -R"Won't do"

# Tilde (~) acts as a not operator
jira issue list -s~Done --created-before -24w -a~x

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

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

jira issue list --history

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

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

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

jira issue list -w -pXYZ

创建

create 命令可让你创建问题。

# Create an issue using an interactive prompt
$ jira issue create

# Pass required parameters and use --no-input option to skip prompt
$ jira issue create -tBug -s"New Bug" -yHigh -lbug -lurgent -b"Bug description" --fix-version v2.0 --no-input

创建问题时，要将史诗关联到问题，可以使用 -P/--parent 字段。我们称之为父级，因为在 next-gen 项目中，史诗的语义已发生变化。

# Create an issue of type Story and attach it to epic with key EPIC-42
$  jira issue create -tStory -s"Epic during creation" -PEPIC-42

你可以使用 --custom 标志，在创建问题时设置自定义字段。更多详情请参阅这篇文章。

该命令支持使用 GitHub 风格 和 Jira 风格的 Markdown 编写描述。你可以使用 --template 标志加载预定义模板。

# Load description from template file
$ jira issue create --template /path/to/template.tmpl

# Get description from standard input
$ jira issue create --template -

# Or, use pipe to read input directly from standard input
$ echo "Description from stdin" | jira issue create -s"Summary" -tTask

上方预览展示了传入 JiraCLI 的 Markdown 模板，以及它在 Jira UI 中的渲染效果。

编辑

edit 命令可让你编辑问题。

$ jira issue edit ISSUE-1

# Edit issue in the configured project
$ jira issue edit ISSUE-1 -s"New Bug" -yHigh -lbug -lurgent -CBackend -b"Bug description"

# Use --no-input option to disable interactive prompt
$ jira issue edit ISSUE-1 -s"New updated summary" --no-input

# Use minus (-) to remove label, component or fixVersion
# For instance, to edit issue to
#   - remove label p2, component FE, fixVersion v1.0
#   - add 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 命令可让你将用户分配给问题。

# Assign user to an issue using an interactive prompt
$ jira issue assign

# Pass required parameters to skip prompt
$ jira issue assign ISSUE-1 "Jon Doe"

# Assign to self
$ jira issue assign ISSUE-1 $(jira me)

# Will prompt for selection if keyword suffix returns multiple entries
$ jira issue assign ISSUE-1 suffix

# Assign to default assignee
$ jira issue assign ISSUE-1 default

# Unassign
$ jira issue assign ISSUE-1 x

移动/转换状态

move 命令可让你将问题从一个状态转换到另一个状态。

# Move an issue using an interactive prompt
$ jira issue move

# Pass required parameters to skip prompt
$ jira issue move ISSUE-1 "In Progress"

如果你的工作流允许在移动问题时添加评论、解决方案或经办人，你可以按如下所示进行操作。 请参阅这份文档，了解如何设置工作流以允许使用这些字段。

# Move an issue and add comment
$ jira issue move ISSUE-1 "In Progress" --comment "Started working on it"

# Set resolution to fixed and assign to self while moving the issue
$ 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 条，出于某些原因，显示的评论可能不是最新的。

# Show 5 recent comments when viewing the issue
$ jira issue view ISSUE-1 --comments 5

关联

link 命令可让你关联两个问题。

# Link an issue using an interactive prompt
$ jira issue link

# Pass required parameters to skip prompt
$ jira issue link ISSUE-1 ISSUE-2 Blocks

远程

remote 命令可让你为问题添加远程网页链接。

# Adds a remote web link using an interactive prompt
$ jira issue link remote

# Pass required parameters to skip prompt
$ jira issue link remote ISSUE-1 https://example.com "Example text"

取消关联

unlink 命令可让你取消两个已关联问题之间的关联。

# Unlink issues using interactive prompt
$ jira issue unlink

# Pass required parameters to skip prompt
$ jira issue unlink ISSUE-1 ISSUE-2

克隆

clone 命令可让你克隆问题。克隆问题时，你可以更新摘要、优先级、经办人、标签和组件等字段。该命令还允许你使用 --replace/-H 选项，在摘要和描述中替换字符串的一部分（区分大小写）。

# Clone an issue
$ jira issue clone ISSUE-1

# Clone issue and modify the summary, priority and assignee
$ jira issue clone ISSUE-1 -s"Modified summary" -yHigh -a$(jira me)

# Clone issue and replace text from summary and description
$ jira issue clone ISSUE-1 -H"find me:replace with me"

删除

delete 命令可让你删除问题。

# Delete an issue using an interactive prompt
$ jira issue delete

# Pass required parameters to skip prompt
$ jira issue delete ISSUE-1

# Delete task along with all of its subtasks
$ jira issue delete ISSUE-1 --cascade

评论

comment 命令提供一系列子命令，用于管理问题评论。

添加

add 命令可让你为问题添加评论。该命令支持使用 GitHub 风格 和 Jira 风格 Markdown 编写 评论。你可以使用 --template 标志加载预定义模板。

# Add a comment using an interactive prompt
$ jira issue comment add

# Pass required parameters to skip prompt
$ jira issue comment add ISSUE-1 "My comment body"

# Same as above but as an internal comment
$ jira issue comment add ISSUE-1 "My comment body" --internal

# Load comment from template file
$ jira issue comment add ISSUE-1 --template /path/to/template.tmpl

# Get comment from standard input
$ jira issue comment add ISSUE-1 --template -

# Or, use pipe to read input directly from standard input
$ echo "Comment from stdin" | jira issue comment add ISSUE-1

说明

如果同时传入评论正文的位置参数和 --template 标志，则始终优先使用位置参数。以下示例中，正文将取自位置参数，而不是模板。

jira issue comment add ISSUE-42 "comment body positional" --template - <<'EOF'
comment body template
EOF

工作日志

worklog 命令提供一系列子命令，用于管理问题工作日志（工时记录）。

添加

add 命令可让你为问题添加工作日志。该命令支持使用 Markdown 编写工作日志评论。

# Add a worklog using an interactive prompt
$ jira issue worklog add

# Pass required parameters and use --no-input to skip prompt
$ jira issue worklog add ISSUE-1 "2d 3h 30m" --no-input

# You can add a comment using --comment flag when adding a worklog
$ jira issue worklog add ISSUE-1 "10m" --comment "This is a comment" --no-input

Epic

默认情况下，Epic 会以资源管理器视图显示。你可以使用 --table 标志以表格视图输出结果。 查看 Epic 问题时，可以使用问题命令支持的所有筛选条件。

请参阅用法，详细了解 UI 交互。

列表

除了问题类型外，你可以在此使用 issue list 命令支持的所有标志。

# List epics
$ jira epic list

# List epics in a table view
$ jira epic list --table

# List epics reported by me and are open
$ jira epic list -r$(jira me) -sOpen

# List issues in an epic
$ jira epic list KEY-1

# List all issue in an epic KEY-1 that is unassigned and has a high priority
$ jira epic list KEY-1 -ax -yHigh

# List high priority epics
$ jira epic list KEY-1 -yHigh

# List epic issues ordered by rank in ascending order
$ jira epic list KEY-1 --order-by rank --reverse

创建

创建 Epic 的方式与创建问题相同，但还需要提供 Epic 名称。

# Create an issue using an interactive prompt
$ jira epic create

# Pass required parameters to skip prompt or use --no-input flag to skip prompt for non-mandatory params
$ jira epic create -n"Epic epic" -s"Everything" -yHigh -lbug -lurgent -b"Epic description"

添加

add 命令可让你将问题添加到 Epic。你一次最多可以向 Epic 添加 50 个问题。

# Add issues to the epic using an interactive prompt
$ jira epic add

# Pass required parameters to skip prompt
$ jira epic add EPIC-KEY ISSUE-1 ISSUE-2

移除

remove 命令可让你从 Epic 中移除问题。你一次最多可以从 Epic 中移除 50 个问题。

# Remove issues to the epic using an interactive prompt
$ jira epic remove

# Pass required parameters to skip prompt
$ jira epic remove ISSUE-1 ISSUE-2

Sprint

默认情况下，Sprint 会以资源管理器视图显示。你可以使用 --table 标志以表格视图输出结果。 查看 Sprint 问题时，可以使用问题命令支持的所有筛选条件。该工具仅显示最近的 25 个 Sprint。

请参阅用法，详细了解 UI 交互。

列表

你可以使用 issue list 命令支持的所有标志来筛选 Sprint 中的问题。

# List sprints in an explorer view
$ jira sprint list

# List sprints in a table view
$ jira sprint list --table

# List issues in the current active sprint
$ jira sprint list --current

# List issues in the current active sprint that are assigned to me
$ jira sprint list --current -a$(jira me)

# List issues in the previous sprint
$ jira sprint list --prev

# List issues in next planned sprint
$ jira sprint list --next

# List future and active sprints
$ jira sprint list --state future,active

# List issues in a particular sprint. You can use all flags supported by issue list command here.
# To get sprint id use `jira sprint list` or `jira sprint list --table`
$ jira sprint list SPRINT_ID

# List high priority issues in a sprint are assigned to me
$ jira sprint list SPRINT_ID -yHigh -a$(jira me)

# List sprint issues ordered by rank in ascending order
$ jira sprint list SPRINT_ID --order-by rank --reverse

添加

add 命令可让你将问题添加到 Sprint。你一次最多可以向 Sprint 添加 50 个问题。

# Add issues to the sprint using interactive prompt
$ jira sprint add

# Pass required parameters to skip prompt
$ jira sprint add SPRINT_ID ISSUE-1 ISSUE-2

发布版本

与发布版本（项目版本）交互。
请确保已在你的实例中启用此功能。

列表

# List releases for default project
$ jira release list

# List releases for specific project
$ jira release list --project 1000
$ jira release list --project KEY

其他命令

jira open

jira open KEY-1

jira project list

jira board list

下面列出了一些示例脚本。

#!/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

# Output
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

# Output
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

# Output
Sprint 3:   5
Sprint 2:   4
Sprint 1:   3

已知问题

1. 目前并非所有 Atlassian 节点都能 正确转换，有时会导致格式问题。

功能请求

请在 ideas 类别中发起讨论，提出你希望添加的功能。

通常如何确定这些请求的优先级？

• 优先处理实现简单、不需要花费太多精力，甚至我偷懒时也能完成的功能。
• 如果某项功能是我日常工作中缺少的，可能会优先处理。
• 其余功能将根据相关功能获得的投票数来确定优先级。

开发

1. 克隆仓库。

   git clone [email protected]:ankitpokhrel/jira-cli.git
   

2. 可选：如果你想在本地运行 Jira 实例，可以使用以下 make 配方。 试用许可证密钥可在 Atlassian 管理页面的“Licenses”部分生成。

   make jira.server
   

3. 修改代码、构建二进制文件并测试你的更改。

   make deps install
   

4. 提交 PR 前，在本地运行 CI 步骤。

   make ci
   

支持项目

我们非常感谢你的建议和反馈。欢迎随时发起讨论 或创建问题，分享你使用该工具的体验，或讨论功能／问题。

如果你认为这个工具很有用，能为你节省大量工作，让你睡得更安稳，不妨通过以下任一方式支持本项目：

• 给仓库点星。
• 在社交媒体上或与朋友分享本项目，帮助宣传。
• 报告错误 或提出解决方案。
• 捐赠一小笔金额。