acli

Atlassian CLI（acli）参考

前置条件

此技能要求安装并完成身份验证的 acli。此技能不包含该二进制文件。

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

验证是否可用：

acli --help

身份验证

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

acli jira auth status
acli admin auth status

如果尚未完成身份验证，可通过以下三种方式进行：

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

acli jira auth login --web

API Token（非交互式，推荐用于 CI/自动化）：

echo "$API_TOKEN" | acli jira auth login --site "mysite.atlassian.net" --email "[email protected]" --token

Admin API Key（仅用于管理员命令）：

echo "$API_KEY" | acli admin auth login --email "[email protected]" --token

切换账户：

acli jira auth switch --site mysite.atlassian.net --email [email protected]
acli admin auth switch --org myorgname

安全

密钥处理

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

破坏性操作

以下命令具有破坏性或不可逆性——执行前始终向用户确认：

• 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 安全规则：

1. 即使提供了 --yes，也绝不要在未获得用户明确确认的情况下运行破坏性命令。
2. 通过 --jql 或 --filter 批量指定目标时，先使用相同的查询执行搜索，向用户展示将受到影响的内容。
3. 执行破坏性更改前，优先使用 --json 输出验证目标。
4. 除非用户明确要求无人值守执行，否则不要将 --yes 与破坏性批量操作结合使用。

组织管理员命令

acli admin 下的命令（包括 admin user activate、deactivate、delete、cancel-delete）会影响整个 Atlassian 组织——影响范围是整个组织，而非单个项目或站点。应将其视为与其他破坏性操作不同的单独级别：

1. 必须在当前轮次重新获得用户确认。 会话前面获得的批准不会沿用到下一个管理员命令。每次都必须重新确认，即使用户刚刚授权执行过类似的管理员命令。
2. 执行前列出已解析的目标。 对于任何 admin user 命令，先将 --email、--id 或 --from-file 输入解析为具体列表（数量以及每个电子邮件地址／账户 ID），并展示给用户。这样可以发现逗号分隔列表中的拼写错误、文件中的过期条目以及含糊的部分匹配。
3. 切勿在 admin user delete 或 admin user deactivate 中使用 --ignore-errors。 批量管理员操作部分失败时，应停止并调查，而非默默继续——相比干净地停止，部分停用更难审计。

命令结构

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

四个顶级命令组：

• acli jira - Jira Cloud 操作（工作项、项目、看板、冲刺、筛选器、仪表板、字段）
• acli admin - 组织管理（用户管理、身份验证）
• acli rovodev - Rovo Dev AI 编码 Agent（Beta）
• acli feedback - 提交反馈／错误报告

常见模式

输出格式

大多数列表／搜索命令支持：--json、--csv 和默认表格输出。

批量操作

通过以下方式指定多个条目：

• --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 可跳过确认提示（适用于自动化）。

分页

• --limit N - 返回的条目数上限（默认值因情况而异：30–50）
• --paginate - 自动获取所有页面（覆盖 --limit）

JSON 模板

许多创建/编辑命令支持使用 --generate-json 生成模板，并使用 --from-json 读取模板：

acli jira workitem create --generate-json > template.json
# edit template.json
acli jira workitem create --from-json template.json

快速参考：最常见的操作

工作项

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

# 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 "[email protected]"

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

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

项目

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"

看板与冲刺

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

命令详细参考

如需查看每条命令的完整标志详情、参数和示例：

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