atlassian-cli

Atlassian CLI（acli）

acli 是 Atlassian 的官方命令行界面，可用于自动执行任务并与 Atlassian Cloud 产品集成。二进制文件名为 acli。官方参考文档：https://developer.atlassian.com/cloud/acli/reference/commands/

顶层命令树

acli
├── admin              # Organization-admin operations
│   ├── auth           # login | logout | status | switch
│   └── user           # activate | cancel-delete | deactivate | delete
├── feedback           # Submit requests or report issues to Atlassian
├── jira               # Jira Cloud operations
│   ├── auth           # login | logout | status | switch
│   ├── board          # list-sprints | search
│   ├── dashboard      # search
│   ├── field          # cancel-delete | create | delete
│   ├── filter         # add-favourite | change-owner | list | search
│   ├── project        # archive | create | delete | list | restore | update | view
│   ├── sprint         # list-workitems
│   └── workitem       # archive | assign | attachment-delete | attachment-list |
│                      # clone | comment-create | comment-delete | comment-list |
│                      # comment-update | comment-visibility | create | create-bulk |
│                      # delete | edit | link | search | transition | unarchive |
│                      # view | watcher-remove
└── rovodev            # Atlassian's AI coding agent (Beta)
    └── auth           # Authenticate Rovo Dev CLI

每个命令和子命令都支持 -h / --help 标志，可显示该命令对应的确切标志集。如果不确定某个标志的签名，请以 acli <command> --help 为准。

身份验证模型

存在两种并行且相互独立的身份验证上下文：

• acli jira auth — 作用于 Jira Cloud 站点（用户令牌或 OAuth）。
• acli admin auth — 作用于 Atlassian 组织管理员账户。

acli jira auth login 接受以下标志：

标志	用途
--web、-w	基于浏览器的 OAuth 流程
--site、-s	Atlassian 站点（例如 mysite.atlassian.net）
--email、-e	用户邮箱（令牌身份验证时必填）
--token	从 stdin 读取 API 令牌（避免将其保留在 shell 历史记录中）

通过 stdin 传递令牌的示例：echo "$API_TOKEN" | acli jira auth login --site mysite.atlassian.net --email [email protected] --token。Windows 上的对应方式使用 Get-Content。

acli jira auth status 会报告当前已通过身份验证的账户；switch 会在登录了多个账户时切换当前账户；logout 会删除凭据。

Jira 工作项命令——核心功能

jira workitem 是功能最丰富的命令组。完整参考文档：references/workitem.md。

选择方式

大多数会修改数据的子命令（edit、assign、transition、delete、archive、unarchive、clone）都接受以下选择器之一：

• --key "KEY-1,KEY-2" — 以逗号分隔的工作项键
• --jql "project = TEAM AND status = 'In Progress'" — JQL 查询
• --filter 10001 — 已保存筛选器的数字 ID
• --from-json path.json — 结构化定义文件
• --from-file path.txt — 纯文本列表（用于 assign）

这种统一的选择模式可通过同一组命令执行批量操作。

常见批量操作标志

标志	行为
--yes	跳过交互式确认
--ignore-errors	发生失败后继续处理剩余项目
--json	输出机器可读内容
--generate-json	输出供 --from-json 使用的 JSON 模板

创建（acli jira workitem create）

必填：--project、--type、--summary。可选：--assignee（使用 @me 表示自己）、--description、--description-file、--label（逗号分隔）、父级关联标志、--from-file、--from-json、--editor、--generate-json、--json。

搜索（acli jira workitem search）

接受 --jql 或 --filter。输出控制选项：--fields（默认值为 issue type, key, assignee, priority, status, summary）、--csv、--json、--limit、--paginate（获取所有页）、--count（仅显示总数）、--web（在浏览器中打开）。

查看（acli jira workitem view KEY-123）

位置参数为工作项键。--fields 接受：

• *all — 所有字段
• *navigable — 可导航字段
• 逗号分隔列表：summary,comment
• 排除项：-description

默认字段集：key,issuetype,summary,status,assignee,description。

状态转换（acli jira workitem transition）

需要一个选择器和 --status "Done"（目标状态名称）。支持批量使用 --key、--jql、--filter。

指派（acli jira workitem assign）

--assignee 接受邮箱、账户 ID、@me 或 default（项目默认值）。--remove-assignee 会清除经办人。

编辑（acli jira workitem edit）

更新摘要、描述、经办人、类型和标签（添加/移除）。支持所有选择器，并支持使用 --generate-json 执行模板化批量更新。

Jira 项目、看板、冲刺、筛选器、字段、仪表板

简明命令参考见 references/jira-other.md。重点：

• jira project create — 三种输入模式：--from-project（克隆）、--from-json（由模板驱动），或直接指定标志（--key、--name、--description、--url、--lead-email）。
• jira project list | view | update | archive | restore | delete — 完整生命周期管理。
• jira board search 和 jira board list-sprints — 看板发现和冲刺枚举。
• jira sprint list-workitems — 列出指定冲刺中的工作项。
• jira filter list | search | add-favourite | change-owner — 已保存筛选器管理。
• jira field create | delete | cancel-delete — 自定义字段生命周期管理（软删除后可恢复）。
• jira dashboard search — 仪表板发现。

管理与 Rovo Dev

请参阅 references/admin-rovodev.md。

• admin user activate | deactivate | delete | cancel-delete — 托管账户生命周期管理。软删除可通过 cancel-delete 撤销。
• admin auth login | logout | status | switch — 组织管理员身份验证，与 Jira 身份验证分开。
• rovodev auth — Rovo Dev CLI 的身份验证（Atlassian 的 AI 编码 Agent，Beta）。

常见工作流示例

典型自动化任务的示例片段（日常站会报告、冲刺滚动、批量重新分配、由 JQL 驱动的导出）见 references/recipes.md。

平台与限制

• 支持 macOS、Linux、Windows；可通过平台包管理器安装（请参阅 Atlassian 安装指南）。
• 不支持 Atlassian Government Cloud。
• 可通过 acli completion setup 启用 Shell 自动补全。