Back to Details

jira-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

jira-cli

jira-cli

Jira Data Center CLI for humans and AI Agents. Supports Jira DC only (self-hosted), not Jira Cloud.
面向人类和AI Agent的Jira Data Center CLI。仅支持Jira DC（自托管），不支持Jira Cloud。

Prerequisites

前提条件

Before using any command, authenticate with a Jira DC instance. Follow these steps in order:
  1. Ask the user for their Jira DC URL (e.g. 
    https://jira.company.com
    ). It must start with 
    https://
    .
  2. Ask the user for a Personal Access Token (PAT). If they don't have one, guide them: "Log in to your Jira DC → click your profile avatar → Personal Access Tokens → Create token."
  3. Run 
    jira-cli login --host <URL> --token <PAT>
    to save credentials.
  4. Run 
    jira-cli doctor --json
    to verify connectivity. If 
    authValid
    is 
    true
    , you're ready.
Important: Credentials are saved locally at 
~/.jira-cli/config.json
. Environment variables 
JIRA_HOST
and 
JIRA_TOKEN
override the config file — use them for CI or when the user prefers not to save credentials.
Always use 
--json
flag when parsing output. Without it, output is human-formatted and not suitable for programmatic use.
使用任何命令之前，请先通过Jira DC实例进行身份验证。按以下顺序操作：
  1. 向用户索要他们的Jira DC URL（例如 
    https://jira.company.com
    ）。URL必须以
    https://
    开头。
  2. 向用户索要个人访问令牌（PAT）。如果用户没有，请引导他们： "登录你的Jira DC → 点击个人资料头像 → 个人访问令牌 → 创建令牌。"
  3. 运行 
    jira-cli login --host <URL> --token <PAT>
    保存凭证。
  4. 运行 
    jira-cli doctor --json
    验证连接性。如果
    authValid
    为
    true
    ，则准备就绪。
重要提示： 凭证会本地保存至
~/.jira-cli/config.json
。环境变量
JIRA_HOST
和
JIRA_TOKEN
会覆盖配置文件——在CI环境中使用，或者当用户不想保存凭证时使用。
解析输出时请始终使用
--json
标志。 不使用该标志时，输出为人类可读格式，不适合编程使用。

Safety

安全注意事项

  • Do NOT use 
    --force
    on destructive commands unless the user explicitly asks.     Commands like 
    issue delete
    prompt for confirmation by default. Skipping confirmation with 
    --force
    is irreversible.
  • Use 
    --dry-run
    before write operations     to preview what will happen without executing. Example: 
    issue create --project PROJ --summary "test" --type Task --dry-run --json
    .
  • AI Agents can make mistakes. Always confirm with the user before executing 
    issue delete
    , 
    issue bulk-transition
    , 
    sprint close
    , or any operation that modifies multiple issues.
  • All write operations are recorded in 
    ~/.jira-cli/audit/
    for traceability.
  • 除非用户明确要求，否则不要在破坏性命令中使用
    --force
    。     诸如
    issue delete
    之类的命令默认会提示确认。使用
    --force
    跳过确认操作是不可逆的。
  • 在执行写入操作前使用
    --dry-run
     预览操作内容而不实际执行。示例：
    issue create --project PROJ --summary "test" --type Task --dry-run --json
    。
  • AI Agent可能会出错。 在执行
    issue delete
    、
    issue bulk-transition
    、
    sprint close
    或任何修改多个Issue的操作之前，请始终与用户确认。
  • 所有写入操作都会记录在
    ~/.jira-cli/audit/
    目录中，以便追溯。

Issue Management

Issue管理

bash
undefined
bash
undefined

View issues (flat JSON by default — token-efficient)

查看Issue（默认输出扁平JSON格式——令牌使用更高效）

jira-cli issue get PROJ-123 --json jira-cli issue get PROJ-123 --json --fields key,summary,status,assignee # Only specific fields jira-cli issue get PROJ-123 --json --raw # Full Jira API response jira-cli issue list --project PROJ --json jira-cli issue list --project PROJ --status "In Progress" --assignee me --json jira-cli issue list --project PROJ --type Bug --priority High --limit 20 --json
jira-cli issue get PROJ-123 --json jira-cli issue get PROJ-123 --json --fields key,summary,status,assignee # 仅返回指定字段 jira-cli issue get PROJ-123 --json --raw # 返回完整的Jira API响应 jira-cli issue list --project PROJ --json jira-cli issue list --project PROJ --status "In Progress" --assignee me --json jira-cli issue list --project PROJ --type Bug --priority High --limit 20 --json

Create and edit

创建与编辑

jira-cli issue create --project PROJ --summary "Fix login bug" --type Bug --json jira-cli issue create --project PROJ --summary "New feature" --type Story --assignee me --priority High --json jira-cli issue create --project PROJ --summary "Sized story" --type Story --field "Story Points=5" --json jira-cli issue edit PROJ-123 --summary "Updated summary" --priority Medium jira-cli issue edit PROJ-123 --field "Story Points=8" --field "Team=Backend" jira-cli issue delete PROJ-123 --force # Skip confirmation prompt
jira-cli issue create --project PROJ --summary "Fix login bug" --type Bug --json jira-cli issue create --project PROJ --summary "New feature" --type Story --assignee me --priority High --json jira-cli issue create --project PROJ --summary "Sized story" --type Story --field "Story Points=5" --json jira-cli issue edit PROJ-123 --summary "Updated summary" --priority Medium jira-cli issue edit PROJ-123 --field "Story Points=8" --field "Team=Backend" jira-cli issue delete PROJ-123 --force # 跳过确认提示

Clone an issue

克隆Issue

jira-cli issue clone PROJ-123 --json # Clone with default summary jira-cli issue clone PROJ-123 --summary "New title" --json # Clone with custom summary jira-cli issue clone PROJ-123 --with-links --json # Clone with issue links
jira-cli issue clone PROJ-123 --json # 使用默认摘要克隆 jira-cli issue clone PROJ-123 --summary "New title" --json # 使用自定义摘要克隆 jira-cli issue clone PROJ-123 --with-links --json # 克隆时包含Issue链接

Status transitions

状态流转

jira-cli issue transitions PROJ-123 --json # List available transitions jira-cli issue transition PROJ-123 "In Progress" # Transition to status (name required) jira-cli issue transition PROJ-123 "Done" --json
jira-cli issue transitions PROJ-123 --json # 列出可用的流转状态 jira-cli issue transition PROJ-123 "In Progress" # 流转到指定状态（需提供状态名称） jira-cli issue transition PROJ-123 "Done" --json

Bulk transition

批量流转

jira-cli issue bulk-transition "Done" --issues PROJ-1,PROJ-2,PROJ-3 --json jira-cli issue bulk-transition "In Progress" --jql "project = PROJ AND sprint = 10 AND status = 'To Do'" --json
jira-cli issue bulk-transition "Done" --issues PROJ-1,PROJ-2,PROJ-3 --json jira-cli issue bulk-transition "In Progress" --jql "project = PROJ AND sprint = 10 AND status = 'To Do'" --json

Assignment and watching

分配与关注

jira-cli issue assign PROJ-123 me # Assign to current user jira-cli issue assign PROJ-123 johndoe # Assign by username (DC uses name, not accountId) jira-cli issue unassign PROJ-123 jira-cli issue watch PROJ-123 jira-cli issue unwatch PROJ-123 jira-cli issue watchers PROJ-123 --json jira-cli issue vote PROJ-123 jira-cli issue unvote PROJ-123
jira-cli issue assign PROJ-123 me # 分配给当前用户 jira-cli issue assign PROJ-123 johndoe # 通过用户名分配（DC使用名称而非accountId） jira-cli issue unassign PROJ-123 jira-cli issue watch PROJ-123 jira-cli issue unwatch PROJ-123 jira-cli issue watchers PROJ-123 --json jira-cli issue vote PROJ-123 jira-cli issue unvote PROJ-123

Comments

评论

jira-cli issue comment add PROJ-123 --body "Fixed in PR #42" --json jira-cli issue comment list PROJ-123 --json jira-cli issue comment delete PROJ-123 --id <commentId>
jira-cli issue comment add PROJ-123 --body "Fixed in PR #42" --json jira-cli issue comment list PROJ-123 --json jira-cli issue comment delete PROJ-123 --id <commentId>

Worklogs

工作日志

jira-cli issue worklog add PROJ-123 --time 2h --comment "Debugging session" --json jira-cli issue worklog add PROJ-123 --time 1h30m --started "2024-01-15T10:00:00.000+0000" jira-cli issue worklog list PROJ-123 --json
jira-cli issue worklog add PROJ-123 --time 2h --comment "Debugging session" --json jira-cli issue worklog add PROJ-123 --time 1h30m --started "2024-01-15T10:00:00.000+0000" jira-cli issue worklog list PROJ-123 --json

Links

链接

jira-cli issue link-types --json # List available link types jira-cli issue link PROJ-123 --to PROJ-456 --type "blocks" jira-cli issue unlink <linkId> jira-cli issue remote-link PROJ-123 --url https://pr.url --title "PR #42" jira-cli issue remote-links PROJ-123 --json
jira-cli issue link-types --json # 列出可用的链接类型 jira-cli issue link PROJ-123 --to PROJ-456 --type "blocks" jira-cli issue unlink <linkId> jira-cli issue remote-link PROJ-123 --url https://pr.url --title "PR #42" jira-cli issue remote-links PROJ-123 --json

Attachments

附件

jira-cli issue attach PROJ-123 --file ./screenshot.png jira-cli issue attachments PROJ-123 --json
undefined
jira-cli issue attach PROJ-123 --file ./screenshot.png jira-cli issue attachments PROJ-123 --json
undefined

Search (JQL)

搜索（JQL）

bash
undefined
bash
undefined

Basic search

基础搜索

jira-cli search "assignee = currentUser() AND status != Done" --json jira-cli search "project = PROJ AND sprint in openSprints()" --json
jira-cli search "assignee = currentUser() AND status != Done" --json jira-cli search "project = PROJ AND sprint in openSprints()" --json

Advanced options

高级选项

jira-cli search "project = PROJ" --limit 100 --json jira-cli search "project = PROJ" --all --json # Fetch ALL results (auto-paginate) jira-cli search "project = PROJ" --count # Only show total count jira-cli search "project = PROJ" --order-by updated --json jira-cli search "type = Bug AND priority = High" --fields key,summary,status --json
undefined
jira-cli search "project = PROJ" --limit 100 --json jira-cli search "project = PROJ" --all --json # 获取所有结果（自动分页） jira-cli search "project = PROJ" --count # 仅显示总数 jira-cli search "project = PROJ" --order-by updated --json jira-cli search "type = Bug AND priority = High" --fields key,summary,status --json
undefined

Sprint Management

Sprint管理

bash
jira-cli board list --json                                          # Find board IDs first
jira-cli sprint list --board 42 --json
jira-cli sprint list --board 42 --state active --json
jira-cli sprint active --board 42 --json                           # Active sprint + issues
jira-cli sprint issues --sprint 10 --json
jira-cli sprint create --board 42 --name "Sprint 5" --start-date 2024-02-01 --end-date 2024-02-14 --json
jira-cli sprint update --sprint 10 --goal "Complete payment refactor"
jira-cli sprint move --sprint 10 --issues PROJ-123,PROJ-124,PROJ-125
jira-cli sprint close --sprint 10 --force                          # --force skips confirmation
bash
jira-cli board list --json                                          # 先查找看板ID
jira-cli sprint list --board 42 --json
jira-cli sprint list --board 42 --state active --json
jira-cli sprint active --board 42 --json                           # 获取活跃Sprint及其中的Issue
jira-cli sprint issues --sprint 10 --json
jira-cli sprint create --board 42 --name "Sprint 5" --start-date 2024-02-01 --end-date 2024-02-14 --json
jira-cli sprint update --sprint 10 --goal "Complete payment refactor"
jira-cli sprint move --sprint 10 --issues PROJ-123,PROJ-124,PROJ-125
jira-cli sprint close --sprint 10 --force                          # --force跳过确认

Board & Backlog

看板与待办事项

bash
jira-cli board list --json
jira-cli board list --project PROJ --type scrum --json
jira-cli board get --board 42 --json
jira-cli board backlog --board 42 --json
jira-cli board epics --board 42 --json
jira-cli board sprints --board 42 --state active --json
bash
jira-cli board list --json
jira-cli board list --project PROJ --type scrum --json
jira-cli board get --board 42 --json
jira-cli board backlog --board 42 --json
jira-cli board epics --board 42 --json
jira-cli board sprints --board 42 --state active --json

Epic Management

Epic管理

bash
jira-cli epic list --board 42 --json
jira-cli epic list --board 42 --done --json              # Completed epics only
jira-cli epic issues PROJ-1 --board 42 --json
bash
jira-cli epic list --board 42 --json
jira-cli epic list --board 42 --done --json              # 仅显示已完成的Epic
jira-cli epic issues PROJ-1 --board 42 --json

Project Management

项目管理

bash
jira-cli project list --json
jira-cli project list --type software --json
jira-cli project get PROJ --json
jira-cli project components PROJ --json
jira-cli project versions PROJ --json
jira-cli project versions PROJ --unreleased --json
jira-cli project issue-types PROJ --json
jira-cli project fields --json                       # List all fields (system + custom)
jira-cli project fields --custom --json              # List custom fields only
bash
jira-cli project list --json
jira-cli project list --type software --json
jira-cli project get PROJ --json
jira-cli project components PROJ --json
jira-cli project versions PROJ --json
jira-cli project versions PROJ --unreleased --json
jira-cli project issue-types PROJ --json
jira-cli project fields --json                       # 列出所有字段（系统字段+自定义字段）
jira-cli project fields --custom --json              # 仅列出自定义字段

User Search

用户搜索

bash
jira-cli user me --json                                  # Current user info
jira-cli user search --query "john" --json
jira-cli user search --query "john" --assignable --project PROJ --json
bash
jira-cli user me --json                                  # 当前用户信息
jira-cli user search --query "john" --json
jira-cli user search --query "john" --assignable --project PROJ --json

Filters

过滤器

bash
jira-cli filter list --json
jira-cli filter get <filterId> --json
jira-cli filter create --name "My Bugs" --jql "assignee = me AND type = Bug" --json
jira-cli filter run <filterId> --json
jira-cli filter delete <filterId>
bash
jira-cli filter list --json
jira-cli filter get <filterId> --json
jira-cli filter create --name "My Bugs" --jql "assignee = me AND type = Bug" --json
jira-cli filter run <filterId> --json
jira-cli filter delete <filterId>

Workflow Examples

工作流示例

Find and update an issue

查找并更新Issue

bash
undefined
bash
undefined

1. Search for issues

1. 搜索Issue

jira-cli search "project = PROJ AND assignee = me AND status = 'In Progress'" --json
jira-cli search "project = PROJ AND assignee = me AND status = 'In Progress'" --json

2. Get issue details

2. 获取Issue详情

jira-cli issue get PROJ-123 --json
jira-cli issue get PROJ-123 --json

3. Check available transitions

3. 查看可用的流转状态

jira-cli issue transitions PROJ-123 --json
jira-cli issue transitions PROJ-123 --json

4. Transition to Done

4. 流转到Done状态

jira-cli issue transition PROJ-123 "Done"
jira-cli issue transition PROJ-123 "Done"

5. Add a comment

5. 添加评论

jira-cli issue comment add PROJ-123 --body "Completed and deployed to staging"
undefined
jira-cli issue comment add PROJ-123 --body "Completed and deployed to staging"
undefined

Sprint planning workflow

Sprint规划工作流

bash
undefined
bash
undefined

1. Find the board

1. 查找看板

jira-cli board list --json
jira-cli board list --json

2. Check active sprint

2. 查看活跃Sprint

jira-cli sprint active --board 42 --json
jira-cli sprint active --board 42 --json

3. View backlog

3. 查看待办事项

jira-cli board backlog --board 42 --json
jira-cli board backlog --board 42 --json

4. Create next sprint

4. 创建下一个Sprint

jira-cli sprint create --board 42 --name "Sprint 6" --start-date 2024-02-15 --end-date 2024-02-28 --json
jira-cli sprint create --board 42 --name "Sprint 6" --start-date 2024-02-15 --end-date 2024-02-28 --json

5. Move issues to sprint

5. 将Issue移入Sprint

jira-cli sprint move --sprint 11 --issues PROJ-200,PROJ-201,PROJ-202
undefined
jira-cli sprint move --sprint 11 --issues PROJ-200,PROJ-201,PROJ-202
undefined

Guardrails

防护措施

  • Always run 
    jira-cli doctor --json
    to verify auth before bulk operations
  • issue delete
    requires typing the issue key to confirm. Use 
    --force
    to skip confirmation in automated workflows
  • sprint close
    is irreversible. Use 
    --force
    to skip confirmation
  • Use 
    --json
    flag when parsing output in scripts or AI workflows
  • Use 
    --dry-run
    to preview what a write command would do without executing it
  • Use 
    --quiet
    with 
    --json
    to suppress all non-JSON output (clean pipe-friendly output)
  • issue transition
    requires the status name as the second argument (no interactive selection)
  • When searching for usernames to use with 
    issue assign
    , use 
    user search --query <name> --json
    first
  • DC uses username (not accountId) for user references. Use 
    jira-cli user me --json
    to find your username
  • 执行批量操作前，务必运行
    jira-cli doctor --json
    验证身份验证
  • issue delete
    需要输入Issue键进行确认。在自动化工作流中使用
    --force
    跳过确认
  • sprint close
    操作不可逆。使用
    --force
    跳过确认
  • 在脚本或AI工作流中解析输出时，请使用
    --json
    标志
  • 使用
    --dry-run
    预览写入命令的执行内容而不实际执行
  • 结合使用
    --quiet
    和
    --json
    抑制所有非JSON输出（适合管道传输的整洁输出）
  • issue transition
    需要将状态名称作为第二个参数（无交互式选择）
  • 使用
    issue assign
    查找用户名时，请先运行
    user search --query <name> --json
  • DC使用用户名（而非accountId）引用用户。运行
    jira-cli user me --json
    查找你的用户名

Global Flags

全局标志

  • --json
    — Output as JSON (machine-readable, flat format by default)
  • --force
    — Skip interactive confirmation prompts (for CI/Agent automation)
  • --quiet
    — Suppress non-JSON stdout output (ideal for scripts and AI Agents)
  • --dry-run
    — Show what would be done without executing (write commands only)
  • --json
    — 以JSON格式输出（机器可读，默认扁平格式）
  • --force
    — 跳过交互式确认提示（适用于CI/Agent自动化）
  • --quiet
    — 抑制非JSON标准输出（适用于脚本和AI Agent）
  • --dry-run
    — 显示操作内容但不执行（仅适用于写入命令）

Output Control Flags

输出控制标志

These flags are available on read commands (
issue get
, 
issue list
, 
search
, 
sprint list
, 
sprint issues
):
  • --raw
    — Return the full raw Jira API response instead of the token-efficient flat format
  • --fields key,summary,status
    — Output only the specified fields (flat JSON mode only)
这些标志适用于读取命令（
issue get
、
issue list
、
search
、
sprint list
、
sprint issues
）：
  • --raw
    — 返回完整的原始Jira API响应，而非令牌高效的扁平格式
  • --fields key,summary,status
    — 仅输出指定字段（仅扁平JSON模式可用）

JSON Output Schemas

JSON输出格式

Flat Issue (default with --json)

扁平Issue格式（使用--json时默认）

json
{
  "key": "PROJ-123",
  "summary": "Fix login bug",
  "status": "In Progress",
  "type": "Bug",
  "assignee": "johndoe",
  "reporter": "janedoe",
  "priority": "High",
  "created": "2024-01-15T10:30:00.000+0000",
  "updated": "2024-01-16T14:20:00.000+0000",
  "labels": "backend,urgent",
  "component": "auth",
  "parent": "PROJ-100"
}
json
{
  "key": "PROJ-123",
  "summary": "Fix login bug",
  "status": "In Progress",
  "type": "Bug",
  "assignee": "johndoe",
  "reporter": "janedoe",
  "priority": "High",
  "created": "2024-01-15T10:30:00.000+0000",
  "updated": "2024-01-16T14:20:00.000+0000",
  "labels": "backend,urgent",
  "component": "auth",
  "parent": "PROJ-100"
}

Flat Sprint

扁平Sprint格式

json
{
  "id": 42,
  "name": "Sprint 5",
  "state": "active",
  "startDate": "2024-02-01",
  "endDate": "2024-02-14",
  "goal": "Complete payment module"
}
json
{
  "id": 42,
  "name": "Sprint 5",
  "state": "active",
  "startDate": "2024-02-01",
  "endDate": "2024-02-14",
  "goal": "Complete payment module"
}

Error Response (with --json)

错误响应（使用--json时）

json
{
  "error": "Jira API error 404: Issue does not exist",
  "statusCode": 404,
  "errorCode": "NOT_FOUND",
  "hint": "Verify the issue key exists and you have permission to view it"
}
json
{
  "error": "Jira API error 404: Issue does not exist",
  "statusCode": 404,
  "errorCode": "NOT_FOUND",
  "hint": "Verify the issue key exists and you have permission to view it"
}

Error Codes

错误代码

CodeStatusHint
AUTH_REQUIRED
401Run 
jira-cli login
or set JIRA_HOST and JIRA_TOKEN
FORBIDDEN
403Check your PAT scope and project permissions
NOT_FOUND
404Verify the resource key/ID exists
RATE_LIMITED
429Wait and retry; reduce request frequency
SERVER_ERROR
5xxJira server error; retry later
NETWORK_ERROR
—Check host URL and network connectivity
CONFIG_ERROR
—Run 
jira-cli login
or set env vars
代码状态提示
AUTH_REQUIRED
401运行
jira-cli login
或设置JIRA_HOST和JIRA_TOKEN
FORBIDDEN
403检查你的PAT权限范围和项目权限
NOT_FOUND
404验证资源键/ID是否存在
RATE_LIMITED
429等待后重试；降低请求频率
SERVER_ERROR
5xxJira服务器错误；稍后重试
NETWORK_ERROR
—检查主机URL和网络连接
CONFIG_ERROR
—运行
jira-cli login
或设置环境变量

Exit Codes

退出代码

CodeMeaning
0Success
2Bad arguments
3Authentication error
4Resource not found
5Forbidden
6Rate limited
7Network/server error
代码含义
0成功
2参数错误
3身份验证错误
4资源未找到
5权限不足
6请求受限
7网络/服务器错误

Audit Logging

审计日志

All write commands are automatically logged to 
~/.jira-cli/audit/
in JSONL format (one file per month). Each entry records the command, arguments, exit code, and duration.
Env varDefaultDescription
JIRA_NO_AUDIT
(unset)Set 
1
to disable audit logging
JIRA_AUDIT_RETENTION_MONTHS
3
Auto-delete files older than N months (
0
= keep forever)
所有写入命令都会自动记录到
~/.jira-cli/audit/
目录中，采用JSONL格式（每月一个文件）。每条记录包含命令、参数、退出代码和执行时长。
环境变量默认值描述
JIRA_NO_AUDIT
（未设置）设置为
1
可禁用审计日志
JIRA_AUDIT_RETENTION_MONTHS
3
自动删除超过N个月的文件（
0
表示永久保留）

Self-Description

自我描述

bash
jira-cli reference   # Print all commands, subcommands, and flags in structured markdown
bash
jira-cli reference   # 以结构化Markdown格式打印所有命令、子命令和标志