acli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Atlassian CLI (acli) Reference

Atlassian CLI (acli) 参考指南

Prerequisites

前提条件

This skill requires

acli

to be installed and authenticated. The binary is NOT bundled with this skill.

If acli is not installed, guide the user to: https://developer.atlassian.com/cloud/acli/guides/install-acli/

Verify availability:

bash

acli --help

使用本技能需要已安装并认证

acli

。该二进制文件未随本技能捆绑提供。

若未安装acli，请引导用户访问：https://developer.atlassian.com/cloud/acli/guides/install-acli/

验证可用性：

bash

acli --help

Authentication

身份验证

Check auth status before running commands:

bash

acli jira auth status
acli admin auth status

If not authenticated, there are three methods:

OAuth (interactive, recommended for users):

bash

acli jira auth login --web

API Token (non-interactive, recommended for CI/automation):

bash

echo "$API_TOKEN" | acli jira auth login --site "mysite.atlassian.net" --email "user@atlassian.com" --token

Admin API Key (for admin commands only):

bash

echo "$API_KEY" | acli admin auth login --email "admin@atlassian.com" --token

Switch between accounts:

bash

acli jira auth switch --site mysite.atlassian.net --email user@atlassian.com
acli admin auth switch --org myorgname

运行命令前检查身份验证状态：

bash

acli jira auth status
acli admin auth status

若未完成身份验证，有三种方式：

OAuth（交互式，推荐普通用户使用）：

bash

acli jira auth login --web

API令牌（非交互式，推荐CI/自动化场景使用）：

bash

echo "$API_TOKEN" | acli jira auth login --site "mysite.atlassian.net" --email "user@atlassian.com" --token

管理员API密钥（仅适用于管理员命令）：

bash

echo "$API_KEY" | acli admin auth login --email "admin@atlassian.com" --token

切换账户：

bash

acli jira auth switch --site mysite.atlassian.net --email user@atlassian.com
acli admin auth switch --org myorgname

Security

安全注意事项

Secret Handling

密钥处理

Never hardcode tokens or API keys in commands. Always use environment variables (
```
$API_TOKEN
```
,
```
$API_KEY
```
) or file-based input (
```
< token.txt
```
).
Never log, echo, or display tokens in output. Avoid piping secrets through intermediate files that persist on disk.
Prefer OAuth (
--web
) for interactive use. Only use token-based auth for CI/automation where OAuth is not feasible.
Do not store tokens in shell history. If using
```
echo "$API_TOKEN" | acli ...
```
, ensure the variable is set in the environment rather than inlined as a literal value.

切勿在命令中硬编码令牌或API密钥。请始终使用环境变量（
```
$API_TOKEN
```
、
```
$API_KEY
```
）或基于文件的输入（
```
< token.txt
```
）。
切勿在输出中记录、回显或显示令牌。避免通过会持久化到磁盘的中间文件传递密钥。
交互式场景优先使用OAuth（
--web
）。仅当OAuth不可行时，才在CI/自动化场景中使用令牌式身份验证。
不要将令牌存储在shell历史记录中。如果使用
```
echo "$API_TOKEN" | acli ...
```
，请确保变量是在环境中设置的，而非作为字面量内联。

Destructive Operations

破坏性操作

The following commands are destructive or irreversible — always confirm with the user before executing:

```
acli jira workitem delete
```
— permanently deletes work items
```
acli jira project delete
```
— permanently deletes a project and all its work items
```
acli admin user delete
```
— deletes managed user accounts
```
acli admin user deactivate
```
— deactivates user accounts
```
acli jira field delete
```
— moves custom fields to trash

These commands are impactful but reversible:

```
acli jira workitem archive
```
/
```
unarchive
```
```
acli jira project archive
```
/
```
restore
```
```
acli admin user cancel-delete
```
— cancels pending deletion
```
acli jira field cancel-delete
```
— restores field from trash

Agent safety rules:

Never run destructive commands without explicit user confirmation, even if
```
--yes
```
is available.
When bulk-targeting via
```
--jql
```
or
```
--filter
```
, first run a search with the same query to show the user what will be affected.
Prefer
```
--json
```
output to verify targets before applying destructive changes.
Do not combine
```
--yes
```
with destructive bulk operations unless the user explicitly requests unattended execution.

以下命令具有破坏性或不可逆性——执行前务必与用户确认：

```
acli jira workitem delete
```
—— 永久删除工作项
```
acli jira project delete
```
—— 永久删除项目及其所有工作项
```
acli admin user delete
```
—— 删除托管用户账户
```
acli admin user deactivate
```
—— 停用用户账户
```
acli jira field delete
```
—— 将自定义字段移至回收站

以下命令影响较大但可撤销：

```
acli jira workitem archive
```
/
```
unarchive
```
```
acli jira project archive
```
/
```
restore
```
```
acli admin user cancel-delete
```
—— 取消待处理的删除操作
```
acli jira field cancel-delete
```
—— 从回收站恢复字段

Agent安全规则：

即使
```
--yes
```
选项可用，也切勿在未获得用户明确确认的情况下运行破坏性命令。
当通过
```
--jql
```
或
```
--filter
```
批量定位时，先使用相同查询执行搜索，向用户展示将受影响的内容。
优先使用
```
--json
```
输出，在应用破坏性更改前验证目标对象。
除非用户明确要求无人值守执行，否则不要将
```
--yes
```
与破坏性批量操作结合使用。

Command Structure

命令结构

acli <command> [<subcommand> ...] {MANDATORY FLAGS} [OPTIONAL FLAGS]

Four top-level command groups:

```
acli jira
```
- Jira Cloud operations (workitems, projects, boards, sprints, filters, dashboards, fields)
```
acli admin
```
- Organization administration (user management, auth)
```
acli rovodev
```
- Rovo Dev AI coding agent (Beta)
```
acli feedback
```
- Submit feedback/bug reports

acli <command> [<subcommand> ...] {MANDATORY FLAGS} [OPTIONAL FLAGS]

四个顶级命令组：

```
acli jira
```
- Jira Cloud操作（工作项、项目、看板、迭代、过滤器、仪表板、字段）
```
acli admin
```
- 组织管理（用户管理、身份验证）
```
acli rovodev
```
- Rovo Dev AI编码Agent（测试版）
```
acli feedback
```
- 提交反馈/错误报告

Common Patterns

通用模式

Output Formats

输出格式

Most list/search commands support:

--json

--csv

, and default table output.

大多数列表/搜索命令支持：

--json

、

--csv

和默认表格输出。

Bulk Operations

批量操作

Target multiple items via:

```
--key "KEY-1,KEY-2,KEY-3"
```
- comma-separated keys

--jql "project = TEAM AND status = 'To Do'"

- JQL query

```
--filter 10001
```
- saved filter ID
```
--from-file "items.txt"
```
- file with keys/IDs (comma/whitespace/newline separated)

Use

--ignore-errors

to continue past failures in bulk operations. Use

--yes

-y

to skip confirmation prompts (useful for automation).

可通过以下方式定位多个项：

```
--key "KEY-1,KEY-2,KEY-3"
```
- 逗号分隔的密钥

--jql "project = TEAM AND status = 'To Do'"

- JQL查询

```
--filter 10001
```
- 已保存过滤器ID
```
--from-file "items.txt"
```
- 包含密钥/ID的文件（逗号/空格/换行分隔）

使用

--ignore-errors

在批量操作中跳过故障继续执行。使用

--yes

-y

跳过确认提示（适用于自动化场景）。

Pagination

分页

```
--limit N
```
- max items to return (defaults vary: 30-50)
```
--paginate
```
- fetch all pages automatically (overrides --limit)

```
--limit N
```
- 返回的最大项数（默认值不同：30-50）
```
--paginate
```
- 自动获取所有页面（覆盖--limit）

JSON Templates

JSON模板

Many create/edit commands support

--generate-json

to produce a template, and

--from-json

to consume it:

bash

acli jira workitem create --generate-json > template.json

许多创建/编辑命令支持

--generate-json

生成模板，以及

--from-json

使用模板：

bash

acli jira workitem create --generate-json > template.json

edit template.json

编辑template.json

acli jira workitem create --from-json template.json

undefined

acli jira workitem create --from-json template.json

undefined

Quick Reference: Most Common Operations

快速参考：最常用操作

Work Items

工作项

bash

undefined

bash

undefined

Create

创建

acli jira workitem create --summary "Fix login bug" --project "TEAM" --type "Bug" acli jira workitem create --summary "New feature" --project "TEAM" --type "Story" --assignee "@me" --label "frontend,p1"

acli jira workitem create --summary "修复登录漏洞" --project "TEAM" --type "Bug" acli jira workitem create --summary "新功能" --project "TEAM" --type "Story" --assignee "@me" --label "frontend,p1"

Search

搜索

acli jira workitem search --jql "project = TEAM AND assignee = currentUser()" --json acli jira workitem search --jql "project = TEAM AND status = 'In Progress'" --fields "key,summary,assignee" --csv

View

查看

acli jira workitem view KEY-123 acli jira workitem view KEY-123 --json --fields "*all"

Edit

编辑

acli jira workitem edit --key "KEY-123" --summary "Updated title" --assignee "user@atlassian.com"

acli jira workitem edit --key "KEY-123" --summary "更新后的标题" --assignee "user@atlassian.com"

Transition

状态转换

acli jira workitem transition --key "KEY-123" --status "Done" acli jira workitem transition --jql "project = TEAM AND sprint in openSprints()" --status "In Progress"

Assign

分配

acli jira workitem assign --key "KEY-123" --assignee "@me"

Comment

添加评论

acli jira workitem comment create --key "KEY-123" --body "Work completed"

acli jira workitem comment create --key "KEY-123" --body "工作已完成"

Bulk create

批量创建

acli jira workitem create-bulk --from-csv issues.csv

undefined

acli jira workitem create-bulk --from-csv issues.csv

undefined

Projects

项目

bash

acli jira project list --paginate --json
acli jira project view --key "TEAM" --json
acli jira project create --from-project "TEAM" --key "NEW" --name "New Project"

bash

acli jira project list --paginate --json
acli jira project view --key "TEAM" --json
acli jira project create --from-project "TEAM" --key "NEW" --name "新项目"

Boards & Sprints

看板与迭代

bash

acli jira board search --project "TEAM"
acli jira board list-sprints --id 123 --state active
acli jira sprint list-workitems --sprint 1 --board 6

bash

acli jira board search --project "TEAM"
acli jira board list-sprints --id 123 --state active
acli jira sprint list-workitems --sprint 1 --board 6

Detailed Command Reference

详细命令参考

For complete flag details, parameters, and examples for every command:

Jira work item commands (create, edit, search, assign, transition, comment, clone, link, archive, attachment, watcher): See references/jira-workitem-commands.md
All other commands (jira project/board/sprint/filter/dashboard/field, admin, rovodev, feedback): See references/other-commands.md

如需了解每个命令的完整标志细节、参数和示例：

Jira工作项命令（创建、编辑、搜索、分配、转换、评论、克隆、关联、归档、附件、关注者）：请查看references/jira-workitem-commands.md
所有其他命令（jira project/board/sprint/filter/dashboard/field、admin、rovodev、feedback）：请查看references/other-commands.md