jira-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Jira CLI

Procedural guide for using the

jira

CLI tool (ankitpokhrel/jira-cli) non-interactively from Claude Code.

从Claude Code非交互式使用

jira

CLI工具（ankitpokhrel/jira-cli）的流程指南。

Critical Rules

重要规则

Always use
--no-input
to suppress interactive prompts (except
```
issue link
```
which does not support it)
Never use
-b
for long descriptions — it causes the CLI to hang. Use file + pipe instead
--template
flag only works on
create
and
comment add
, not on
```
edit
```
The CLI uses a markdown-to-ADF parser — see references/formatting.md for what works and what breaks
Pipe from stdin for descriptions longer than 2-3 lines
Avoid special characters in descriptions — parentheses
```
()
```
, angle brackets
```
<>
```
, underscores
```
_
```
, and arrows
```
->
```
get escaped by the markdown parser inside code blocks

**始终使用
```
--no-input
```
**来抑制交互式提示（
```
issue link
```
命令除外，该命令不支持此参数）
切勿使用
-b
参数处理长描述——这会导致CLI挂起。请改用文件+管道的方式
--template
参数仅适用于
create
和
comment add
命令，不适用于
```
edit
```
命令
该CLI使用markdown到ADF的解析器——请查看references/formatting.md了解支持和不支持的格式
对于超过2-3行的描述，从标准输入（stdin）管道输入
避免在描述中使用特殊字符——括号
```
()
```
、尖括号
```
<>
```
、下划线
```
_
```
和箭头
```
->
```
会被代码块内的markdown解析器转义

Quick Reference

快速参考

Check auth

检查认证

bash

jira me

bash

jira me

Create issue

创建问题

bash

undefined

bash

undefined

Short description

短描述

jira issue create -p PROJECT -t Task -s "Summary" -y High --no-input

Long description (ALWAYS use this pattern)

长描述（务必使用此模式）

cat /tmp/jira-body.md | jira issue create -p PROJECT -t Task -s "Summary" -y High --template - --no-input

undefined

cat /tmp/jira-body.md | jira issue create -p PROJECT -t Task -s "Summary" -y High --template - --no-input

undefined

View issue

查看问题

bash

jira issue view KEY --plain        # Human-readable
jira issue view KEY --raw          # JSON for scripting

bash

jira issue view KEY --plain        # 人类可读格式
jira issue view KEY --raw          # 用于脚本的JSON格式

Edit issue

编辑问题

bash

jira issue edit KEY -s "New summary" --no-input
echo "New description" | jira issue edit KEY --no-input    # Replaces description entirely

bash

jira issue edit KEY -s "New summary" --no-input
echo "New description" | jira issue edit KEY --no-input    # 完全替换描述内容

List issues

列出问题

bash

jira issue list --plain                                    # All issues
jira issue list -s "In Progress" --plain                   # By status
jira issue list -q "assignee = currentUser()" --plain      # Custom JQL

bash

jira issue list --plain                                    # 所有问题
jira issue list -s "In Progress" --plain                   # 按状态筛选
jira issue list -q "assignee = currentUser()" --plain      # 自定义JQL查询

Transition issue

流转问题状态

bash

jira issue move KEY "In Progress"
jira issue move KEY Done --comment "Completed in PR #123"

bash

jira issue move KEY "In Progress"
jira issue move KEY Done --comment "Completed in PR #123"

Sprint operations

Sprint操作

bash

jira sprint list --state active              # Active sprints
jira sprint list --current --plain           # Issues in current sprint
jira sprint add SPRINT_ID KEY1 KEY2          # Add issues to sprint

For the full command reference, see references/commands.md.

bash

jira sprint list --state active              # 活跃Sprint
jira sprint list --current --plain           # 当前Sprint中的问题
jira sprint add SPRINT_ID KEY1 KEY2          # 向Sprint添加问题

完整命令参考请查看references/commands.md。

Long Description Workflow

长描述工作流

For any description longer than 2-3 lines, ALWAYS write to a temp file and pipe.

Use the hybrid formatting that survives the CLI's markdown-to-ADF conversion:

```
h2.
```
headings (wiki syntax — these survive)
```
||Header||
```
tables (wiki syntax — these survive)
```
*bold*
```
for emphasis
```
* item
```
for bullet lists (NOT
```
#
```
for numbered lists)
Triple backtick fenced code blocks (NOT
```
{code}
```
or
```
{noformat}
```
)
Plain text for issue keys like SPRINT-123 (auto-linked by Jira)
Avoid
```
()
```
,
```
<>
```
,
```
_
```
,
```
->
```
inside code blocks (they get escaped)

bash

undefined

对于任何超过2-3行的描述，务必写入临时文件后通过管道输入。

使用能在CLI的markdown到ADF转换中保留的混合格式：

```
h2.
```
标题（wiki语法——可保留）
```
||表头||
```
表格（wiki语法——可保留）
```
*粗体*
```
用于强调
```
* 列表项
```
用于无序列表（请勿使用
```
#
```
表示有序列表）
三个反引号包裹的代码块（请勿使用
```
{code}
```
或
```
{noformat}
```
）
问题键如SPRINT-123使用纯文本（Jira会自动链接）
避免在代码块内使用
```
()
```
、
```
<>
```
、
```
_
```
、
```
->
```
（这些字符会被转义）

bash

undefined

1. Write description using hybrid formatting

1. 使用混合格式编写描述

cat > /tmp/jira-body.md << 'DESCRIPTION' h2. Context

Description content here...

h2. Acceptance Criteria

Criterion one
Criterion two

h2. Technical Notes

code goes here with no special chars

DESCRIPTION

cat > /tmp/jira-body.md << 'DESCRIPTION' h2. Context

Description content here...

h2. Acceptance Criteria

Criterion one
Criterion two

h2. Technical Notes

code goes here with no special chars

DESCRIPTION

2a. Create issue

2a. 创建问题

cat /tmp/jira-body.md | jira issue create -p PROJECT -t Task -s "Summary" -y High --template - --no-input

2b. OR edit existing issue (no --template flag)

2b. 或编辑现有问题（不使用--template参数）

cat /tmp/jira-body.md | jira issue edit KEY --no-input

3. Clean up

3. 清理文件

rm /tmp/jira-body.md


See [references/formatting.md](references/formatting.md) for the complete guide on what renders correctly.

rm /tmp/jira-body.md


有关正确渲染格式的完整指南，请查看[references/formatting.md](references/formatting.md)。

Common Gotchas

常见陷阱

Pitfall	Cause	Solution
`-b` with long content hangs	CLI buffer issue	Use file + pipe with `--template -`
`--template` on `edit`	Not a valid flag for edit	Pipe from stdin instead
`#` renders as heading	CLI's markdown parser interprets `#` as heading	Use `* bullet` lists or tables with numbered rows
`{code:sql}...{code}` content mangled	Markdown parser escapes `()` , `_` , `->` inside wiki code blocks	Use triple backtick fenced code blocks instead
`{noformat}` content escaped	Same markdown parser issue	Use triple backtick fenced code blocks
`{{inline code}}` broken	Wiki syntax not recognized by markdown parser	Avoid or use plain text
`[text\|url]` link broken	Wiki link syntax conflicts with markdown parser	Write ticket keys as plain text (auto-linked) or use markdown `[text](url)`
`--no-input` on `issue link`	Flag not supported on this subcommand	Omit the flag: `jira issue link KEY1 KEY2 Blocks`
Create command takes 5-10s	Normal Jira Cloud API latency	Expected behavior

陷阱	原因	解决方案
使用 `-b` 处理长内容时CLI挂起	CLI缓冲区问题	使用文件+管道结合 `--template -` 的方式
在 `edit` 命令上使用 `--template` 参数	该参数对edit命令无效	改为从标准输入管道输入
`#` 被渲染为标题	CLI的markdown解析器将 `#` 识别为标题	使用 `* 项目符号` 列表或带编号行的表格
`{code:sql}...{code}` 内容被破坏	Markdown解析器会转义wiki代码块内的 `()` 、 `_` 、 `->`	改用三个反引号包裹的代码块
`{noformat}` 内容被转义	同样是markdown解析器的问题	改用三个反引号包裹的代码块
`{{行内代码}}` 无法正常显示	Markdown解析器不识别wiki语法	避免使用或改用纯文本
`[text\|url]` 链接失效	Wiki链接语法与markdown解析器冲突	工单键使用纯文本（会自动链接）或使用markdown格式 `[text](url)`
在 `issue link` 命令上使用 `--no-input`	该子命令不支持此参数	省略该参数： `jira issue link KEY1 KEY2 Blocks`
创建命令耗时5-10秒	Jira Cloud API的正常延迟	属于预期行为

Resources

参考资源

references/commands.md — Full CLI command reference with all flags and examples
references/formatting.md — What formatting survives the CLI's markdown-to-ADF conversion (the critical reference for writing descriptions)

references/commands.md — 包含所有参数和示例的完整CLI命令参考
references/formatting.md — 详细说明CLI的markdown到ADF转换中可保留的格式（这是编写描述的关键参考）