jira

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Jira with orbit CLI

使用orbit CLI管理Jira

Manage Jira issues, epics, sprints, boards, projects, releases, custom fields, screens, statuses, and issue types using the

orbit

CLI. Supports both Jira Cloud (REST API v3) and Jira Server/Data Center (REST API v2) with multi-profile support and 1Password secret resolution.

通过

orbit

CLI管理Jira的issues、epics、sprints、看板、项目、发布版本、自定义字段、屏幕、状态和问题类型。支持Jira Cloud（REST API v3）和Jira Server/数据中心（REST API v2），具备多profile支持和1Password密钥自动解析功能。

Prerequisites

前提条件

```
orbit
```
binary built and accessible

A profile with a

jira-cloud

jira-onprem

service configured in

~/.config/orbit/config.yaml

Valid credentials — API token for Cloud (basic auth with email + token), PAT for Server
Credentials can be stored in 1Password with
```
op://
```
prefix for automatic resolution

```
orbit
```
二进制文件已编译且可访问

在

~/.config/orbit/config.yaml

中配置了带有

jira-cloud

或

jira-onprem

服务的profile

有效的凭据——Cloud版本使用API令牌（邮箱+令牌的基础认证），Server版本使用PAT
凭据可存储在1Password中，使用
```
op://
```
前缀可自动解析

Quick Reference

快速参考

All commands follow the pattern:

orbit -p <profile> jira <resource> <action> [flags]

The

-o

flag controls output format:

table

(default),

json

yaml

For full command details and flags, see

references/commands.md

. For Jira wiki markup formatting (Server only), see

references/wiki-markup.md

所有命令遵循以下格式：

orbit -p <profile> jira <resource> <action> [flags]

-o

标志控制输出格式：

table

（默认）、

json

、

yaml

。

如需完整命令详情和标志说明，请查看

references/commands.md

。如需Jira wiki markup格式说明（仅Server版本），请查看

references/wiki-markup.md

。

Core Workflows

核心工作流

Creating Issues

创建Issues

bash

undefined

bash

undefined

Simple story

创建简单的Story

orbit -p myprofile jira issue create --project PROJ --type Story --summary "Add login page"

orbit -p myprofile jira issue create --project PROJ --type Story --summary "添加登录页面"

Bug with priority and assignment

创建带优先级和分配人的Bug

orbit -p myprofile jira issue create --project PROJ --type Bug
--summary "Fix timeout" --priority High --assignee john.doe

orbit -p myprofile jira issue create --project PROJ --type Bug
--summary "修复超时问题" --priority High --assignee john.doe

Sub-task under a parent

创建隶属于父级的子任务

orbit -p myprofile jira issue create --project PROJ --type Sub-task
--parent PROJ-123 --summary "Add validation"

undefined

orbit -p myprofile jira issue create --project PROJ --type Sub-task
--parent PROJ-123 --summary "添加验证功能"

undefined

Creating Epics

创建Epics

Epics require the "Epic Name" custom field. The

orbit

CLI auto-sets this from the summary when

--type Epic

is used. Use

--epic-name

to override.

bash

undefined

Epics需要“Epic Name”自定义字段。当使用

--type Epic

时，

orbit

CLI会自动从summary中设置该字段。可使用

--epic-name

覆盖默认值。

bash

undefined

Create an epic (Epic Name auto-set from summary)

创建Epic（Epic Name自动从summary获取）

orbit -p myprofile jira issue create --type Epic --project PROJ
--summary "Q1 Auth Revamp" --priority Highest

orbit -p myprofile jira issue create --type Epic --project PROJ
--summary "Q1认证体系重构" --priority Highest

Create epic with Parent Link to a Capability/Initiative

创建带有父级链接（关联Capability/Initiative）的Epic

orbit -p myprofile jira issue create --type Epic --project PROJ
--summary "Okta Authentication Foundation"
--field "customfield_27521=PRT-4378"
--priority Highest


The `--field` flag sets arbitrary custom fields as `key=value`. Use `jira field list` to discover field IDs.

orbit -p myprofile jira issue create --type Epic --project PROJ
--summary "Okta认证基础架构"
--field "customfield_27521=PRT-4378"
--priority Highest


`--field`标志用于设置任意自定义字段，格式为`key=value`。可使用`jira field list`命令查看字段ID。

Editing Issues with Formatted Descriptions

编辑带有格式化描述的Issues

Jira Server uses wiki markup, not Markdown. Jira Cloud uses ADF (handled automatically by orbit for plain text). Always format

--body

values using wiki markup syntax for Server instances.

bash

orbit -p myprofile jira issue edit PRT-123 --body "h2. Value Statement

The platform provides real authentication via Okta.

h2. User Stories

* *Story 1:* As a platform admin, I want all API requests to require a valid Okta JWT.
** Okta custom AS configured with epsilon_claims claim
** AUTH_BYPASS removed from all Terraform task definitions"

Jira Server使用wiki markup而非Markdown。Jira Cloud使用ADF格式（orbit会自动处理纯文本内容）。对于Server实例，务必使用wiki markup语法格式化

--body

参数的值。

bash

orbit -p myprofile jira issue edit PRT-123 --body "h2. 价值声明

该平台通过Okta提供真实的认证服务。

h2. 用户故事

* *故事1:* 作为平台管理员，我希望所有API请求都需要有效的Okta JWT。
** 已配置带有epsilon_claims声明的Okta自定义AS
** 已从所有Terraform任务定义中移除AUTH_BYPASS"

Editing Custom Field Values

编辑自定义字段值

The

-F

flag supports multiple value formats. The correct format depends on the Jira field type:

bash

undefined

-F

标志支持多种值格式，具体格式取决于Jira字段类型：

bash

undefined

Single-select field — use value: shorthand

单选字段——使用value:简写格式

orbit -p myprofile jira issue edit PROJ-123 -F customfield_10397=value:Yes

Multi-select field — MUST use JSON array of objects (value: shorthand will return 400)

多选字段——必须使用JSON对象数组格式（使用value:简写会返回400错误）

orbit -p myprofile jira issue edit PROJ-123 -F 'customfield_10398=[{"value":"Developer"},{"value":"QA"}]'

Multi-select with a single value still needs array format

单个值的多选字段仍需使用数组格式

orbit -p myprofile jira issue edit PROJ-123 -F 'customfield_10400=[{"value":"Confirmed"}]'

Number field

数字字段

orbit -p myprofile jira issue edit PROJ-123 -F customfield_10399=3

Plain string field

纯字符串字段

orbit -p myprofile jira issue edit PROJ-123 -F customfield_10010=my-value


**Important**: Multi-select fields (checkboxes, multi-select dropdowns) require `[{"value":"X"}]` array format. Using `value:X` on a multi-select field returns a 400 error.

orbit -p myprofile jira issue edit PROJ-123 -F customfield_10010=my-value


**重要提示**：多选字段（复选框、多选下拉框）需要使用`[{"value":"X"}]`数组格式。对多选字段使用`value:X`格式会返回400错误。

Transitioning Issues

转换Issues状态

bash

undefined

bash

undefined

Move to In Progress

移至“进行中”状态

orbit -p myprofile jira issue move PROJ-123 "In Progress"

Close with comment and resolution

关闭Issue并添加评论和解决结果

orbit -p myprofile jira issue move PROJ-123 Done --comment "Fixed in v2.1" --resolution Fixed

undefined

orbit -p myprofile jira issue move PROJ-123 Done --comment "已在v2.1版本修复" --resolution Fixed

undefined

Searching Issues

搜索Issues

bash

undefined

bash

undefined

Filter by project and type

按项目和类型筛选

orbit -p myprofile jira issue list --project PROJ --type Epic

Filter by assignee and status

按经办人状态筛选

orbit -p myprofile jira issue list --assignee me --status "In Progress"

Raw JQL query

原始JQL查询

orbit -p myprofile jira issue list --jql "project = PROJ AND sprint in openSprints()"

JSON output for processing

输出JSON格式以便后续处理

orbit -p myprofile jira issue list --project PROJ -o json

undefined

orbit -p myprofile jira issue list --project PROJ -o json

undefined

Field Management (Cloud Only)

字段管理（仅Cloud版本）

Manage custom fields, their contexts, and options programmatically.

以编程方式管理自定义字段、字段上下文和选项。

Listing Fields

列出字段

bash

undefined

bash

undefined

List all fields

列出所有字段

orbit -p myprofile jira field list

List only custom fields

仅列出自定义字段

orbit -p myprofile jira field list --custom

Filter by name or ID

按名称或ID筛选

orbit -p myprofile jira field list --filter "AI"

undefined

orbit -p myprofile jira field list --filter "AI"

undefined

Creating Custom Fields

创建自定义字段

bash

undefined

bash

undefined

Create a select field (shorthand types: select, multiselect, number, checkbox, text, textarea)

创建单选字段（简写类型：select、multiselect、number、checkbox、text、textarea）

orbit -p myprofile jira field create --name "AI Assisted" --type select
--description "Was AI used on this ticket?"

orbit -p myprofile jira field create --name "AI辅助标识" --type select
--description "此工单是否使用了AI？"

Create a number field

创建数字字段

orbit -p myprofile jira field create --name "AI Prompt Iterations" --type number
--description "How many prompt cycles to get working output"

orbit -p myprofile jira field create --name "AI提示迭代次数" --type number
--description "获得可用输出所需的提示循环次数"

Create a checkbox field

创建复选框字段

orbit -p myprofile jira field create --name "Human Review Confirmed" --type checkbox
--description "Engineer confirms AI output was reviewed"

undefined

orbit -p myprofile jira field create --name "人工审核确认" --type checkbox
--description "工程师确认已审核AI输出"

undefined

Managing Field Contexts and Options

管理字段上下文和选项

bash

undefined

bash

undefined

List field contexts

列出字段上下文

orbit -p myprofile jira field context-list customfield_10397

List existing options

列出现有选项

orbit -p myprofile jira field option-list customfield_10397 10817

Add options to a select/multiselect field

为单选/多选字段添加选项

orbit -p myprofile jira field option-add customfield_10397 10817
--values "Yes,No,Partial"

undefined

orbit -p myprofile jira field option-add customfield_10397 10817
--values "Yes,No,Partial"

undefined

Screen Management

屏幕管理

Control which fields appear on issue create/edit/view forms by managing screen tabs and field assignments.

通过管理屏幕标签页和字段分配，控制在创建/编辑/查看Issue的表单中显示哪些字段。

Listing Screens and Tabs

列出屏幕和标签页

bash

undefined

bash

undefined

List all screens

列出所有屏幕

orbit -p myprofile jira screen list

Filter screens by name

按名称筛选屏幕

orbit -p myprofile jira screen list --filter "PYMT"

List tabs on a screen

列出屏幕的标签页

orbit -p myprofile jira screen tab-list 10089

List fields on a screen tab

列出屏幕标签页上的字段

orbit -p myprofile jira screen field-list 10089 10189

undefined

orbit -p myprofile jira screen field-list 10089 10189

undefined

Creating Tabs

创建标签页

bash

undefined

bash

undefined

Create a new tab to group related fields

创建新标签页以分组相关字段

orbit -p myprofile jira screen tab-create 10089 "AI Workflow"

undefined

orbit -p myprofile jira screen tab-create 10089 "AI工作流"

undefined

Adding and Removing Fields

添加和移除字段

bash

undefined

bash

undefined

Add fields to a screen tab

向屏幕标签页添加字段

orbit -p myprofile jira screen field-add 10089 10868
--fields "customfield_10397,customfield_10398,customfield_10399"

Remove fields from a screen tab

从屏幕标签页移除字段

orbit -p myprofile jira screen field-remove 10089 10189
--fields "customfield_10397,customfield_10398"

undefined

orbit -p myprofile jira screen field-remove 10089 10189
--fields "customfield_10397,customfield_10398"

undefined

Moving Fields Between Tabs

在标签页之间移动字段

bash

undefined

bash

undefined

Move fields from General tab to AI Workflow tab

将字段从“常规”标签页移至“AI工作流”标签页

orbit -p myprofile jira screen field-move 10089 10189 10868
--fields "customfield_10397,customfield_10398,customfield_10399"

undefined

orbit -p myprofile jira screen field-move 10089 10189 10868
--fields "customfield_10397,customfield_10398,customfield_10399"

undefined

Status and Issue Type Management

状态和问题类型管理

Listing Workflow Statuses

列出工作流状态

bash

undefined

bash

undefined

List all statuses with their categories

列出所有状态及其分类

orbit -p myprofile jira status list

Filter with grep

使用grep筛选

orbit -p myprofile jira status list | grep -i "review"

undefined

orbit -p myprofile jira status list | grep -i "review"

undefined

Listing Issue Types

列出问题类型

bash

orbit -p myprofile jira issuetype-list

bash

orbit -p myprofile jira issuetype-list

Deleting Issues

删除Issues

Delete issues with

issue delete

. Use

--cascade

to also delete all subtasks.

Important: There is no

--confirm

--force

flag. The command deletes immediately.

bash

undefined

使用

issue delete

命令删除Issues。使用

--cascade

标志可同时删除所有子任务。

重要提示：该命令没有

--confirm

或

--force

标志，执行后会立即删除。

bash

undefined

Delete a single issue

删除单个Issue

orbit -p myprofile jira issue delete PROJ-123

Delete an issue and all its subtasks

删除Issue及其所有子任务

orbit -p myprofile jira issue delete PROJ-100 --cascade


**Deleting a hierarchy (parent → children → grandchildren):** Delete bottom-up to avoid orphan errors, or use `--cascade` at each level that has subtasks.

```bash

orbit -p myprofile jira issue delete PROJ-100 --cascade


**删除层级结构（父级→子级→孙级）**：需从下往上删除以避免孤儿错误，或在每个有子任务的层级使用`--cascade`标志。

```bash

Example: delete Story (with sub-tasks) → Epic → Capability

示例：删除Story（含子任务）→ Epic → Capability

orbit -p myprofile jira issue delete PROJ-50 --cascade # Story + sub-tasks orbit -p myprofile jira issue delete PROJ-40 # Epic (now childless) orbit -p myprofile jira issue delete PRT-200 # Capability (now childless)


**Tip:** `--cascade` only deletes Jira sub-tasks (child issues of type Sub-task). It does NOT delete Stories under an Epic or Epics under a Capability. For full hierarchy deletion, query children with JQL first, then delete bottom-up.

```bash

orbit -p myprofile jira issue delete PROJ-50 --cascade # Story + 子任务 orbit -p myprofile jira issue delete PROJ-40 # Epic（已无子任务） orbit -p myprofile jira issue delete PRT-200 # Capability（已无子任务）


**提示**：`--cascade`仅会删除Jira子任务（类型为Sub-task的子Issue），不会删除Epic下的Story或Capability下的Epic。如需删除完整层级结构，需先使用JQL查询子级，再从下往上删除。

```bash

Find all children of an issue

查找某个Issue的所有子级

orbit -p myprofile jira issue list --jql '"Parent" = PROJ-40' -o json

undefined

orbit -p myprofile jira issue list --jql '"Parent" = PROJ-40' -o json

undefined

Important Notes

重要说明

Cloud vs Server — Use service type
```
jira-cloud
```
for Atlassian Cloud (uses API v3 with ADF for descriptions). Use
```
jira-onprem
```
for Server/Data Center (uses API v2 with wiki markup).
Description formatting — For Server instances, always use Jira wiki markup for
```
--body
```
values. For Cloud, orbit auto-converts plain text to ADF. See
```
references/wiki-markup.md
```
for wiki markup syntax.

Field management —

field create

field context-list

field option-list

, and

field option-add

are Cloud-only features.

Screen management — Adding fields to screens makes them appear on issue create/edit forms. Use
```
tab-create
```
to group related fields into a dedicated tab.
Epic type cannot use
--parent
flag — Jira rejects it because Epic is not a sub-task type. Use the
```
--field "customfield_27521=KEY"
```
(Parent Link) instead.
1Password integration — Credentials in config can use
```
op://vault/item/field
```
and are resolved at runtime. Run
```
orbit auth
```
once to resolve and cache all secrets for 8 hours (single biometric prompt). Use
```
orbit auth clear
```
to wipe the cache. Without
```
orbit auth
```
, secrets are still resolved on each command but may trigger repeated biometric prompts.

Cloud与Server版本差异 —— Atlassian Cloud版本使用
```
jira-cloud
```
服务类型（使用API v3，描述采用ADF格式）。Server/数据中心版本使用
```
jira-onprem
```
服务类型（使用API v2，描述采用wiki markup格式）。
描述格式 —— 对于Server实例，
```
--body
```
参数的值务必使用Jira wiki markup格式。对于Cloud版本，orbit会自动将纯文本转换为ADF格式。wiki markup语法说明请查看
```
references/wiki-markup.md
```
。

字段管理 ——

field create

、

field context-list

、

field option-list

和

field option-add

是仅Cloud版本支持的功能。

屏幕管理 —— 向屏幕添加字段后，这些字段会显示在Issue的创建/编辑表单中。可使用
```
tab-create
```
命令将相关字段分组到专属标签页。
Epic类型无法使用
--parent
标志 —— Jira会拒绝该操作，因为Epic不属于子任务类型。请使用
```
--field "customfield_27521=KEY"
```
（父级链接）替代。
1Password集成 —— 配置文件中的凭据可使用
```
op://vault/item/field
```
格式，运行时会自动解析。执行一次
```
orbit auth
```
命令即可解析并缓存所有密钥，有效期8小时（仅需一次生物识别验证）。使用
```
orbit auth clear
```
命令可清除缓存。若未执行
```
orbit auth
```
，每次命令执行时仍会解析密钥，但可能会重复触发生物识别验证。