Atlassian aCLI Reference Skill for Jira and Confluence

核心用法

acli 是 Atlassian 官方提供的命令行工具，用于在终端中直接操作 Jira Cloud 和组织管理功能。主要覆盖四大模块：

Jira 操作 (acli jira)：完整的工作项生命周期管理（创建、编辑、搜索、分配、状态流转、评论、克隆、链接、归档），以及项目、看板、冲刺、筛选器、仪表板和字段的管理。

组织管理 (acli admin)：用户账户管理（激活、停用、删除）、身份认证配置，操作范围覆盖整个 Atlassian 组织而非单个项目。

Rovo Dev (acli rovodev)：Beta 阶段的 AI 编码助手集成。

认证方式：支持交互式 OAuth（--web 推荐日常使用）、非交互式 API Token（CI/自动化场景）以及 Admin API Key（仅限管理命令）。

显著优点

• 官方维护：Atlassian 原生开发，API 兼容性和长期支持有保障
• 功能完整：覆盖 Jira Web 端绝大多数操作，支持 JSON/CSV 多格式输出
• 批量操作：通过 --jql、--filter、--from-file 实现大规模工作项处理
• 模板化工作流：--generate-json 与 --from-json 支持可复用的配置模板
• 安全设计：强制环境变量传递密钥，禁止硬编码；区分 destructive/reversible 操作等级

潜在缺点与局限

• 环境依赖：必须独立安装 acli 二进制文件（约 100MB+），不支持无网络环境的纯离线使用
• 认证复杂度：组织级管理需额外 Admin API Key，多站点切换需手动管理 auth 状态
• 学习成本：命令层级较深（acli jira workitem transition --key ...），flags 记忆负担较重
• Beta 功能风险：Rovo Dev 模块尚处于早期阶段，接口稳定性无保障

适合人群

• 需要高频批量操作 Jira 的开发者、Scrum Master、项目经理
• 构建 CI/CD 流水线自动化（如自动创建发布任务、状态流转）的 DevOps 工程师
• 管理多站点/多组织 Atlassian 账户的企业管理员

常规风险

• 密钥泄露：API Token 若写入 shell history 或日志可能导致账户接管
• 误操作影响面大：admin user delete 等命令影响整个组织，且部分操作不可逆
• 批量操作失控：JQL 语法错误可能导致误删/误改大量工作项，建议先 --json 预览再执行
• 权限蔓延：长期有效的 API Token 需定期轮换，避免离职人员凭证残留

核心用法

该 Skill 是 Atlassian CLI (acli) 的纯文档型参考指南，旨在帮助用户通过命令行高效管理 Jira Cloud 和 Atlassian 组织。核心功能覆盖四大领域：

1. Jira 工作项管理：创建、编辑、搜索、分配、状态流转、评论、克隆、链接、归档等全生命周期操作。支持通过 --jql 查询语言进行批量操作，以及通过 --from-csv / --from-json 实现结构化数据导入。

2. 项目与看板管理：项目创建、列表查看、更新归档；敏捷看板搜索、Sprint 管理、工作项 Sprint 关联等敏捷开发场景支持。

3. 组织级管理：用户账户的激活、停用、删除；认证配置管理等 Atlassian Admin 权限范围内的运维操作。

4. 安全自动化：强调环境变量注入（$API_TOKEN、$API_KEY）、OAuth 交互式认证、以及破坏性操作的多重确认机制。

使用模式上，用户需预先在系统安装并认证 acli 二进制文件，该 Skill 不提供可执行代码，仅输出规范化的命令参考和安全指引。

---

显著优点

| 优势维度 | 具体体现 |

|---------|---------|

| **安全设计领先** | 文档内嵌完整的安全规范章节，强制要求环境变量传参、禁止硬编码凭证、明确标注破坏性操作（delete/deactivate）的确认流程，体现安全优先的设计理念 |

| **零攻击面** | 纯 Markdown 文档，无 JavaScript/Python/Shell 等可执行代码，无 package.json/requirements.txt，彻底杜绝供应链攻击和代码注入风险 |

| **操作覆盖全面** | 涵盖 acli 全部四大命令组（jira/admin/rovodev/feedback），从单条工作项查看到批量 JQL 查询、从项目创建到组织级用户管理的完整能力谱系 |

| **企业级批量能力** | 原生支持 `--paginate` 全量拉取、`--ignore-errors` 容错执行、`--from-file` 批量输入等自动化场景必备特性，契合 CI/CD 集成需求 |

| **模板化工作流** | `--generate-json` / `--from-json` 的模板化创建模式，降低复杂对象（如工作项、项目）的配置门槛，支持版本化管理 |

---

潜在缺点与局限性

1. 外部依赖刚性：Skill 本身仅为文档，所有命令执行依赖系统预装的 acli 二进制文件。若用户环境未安装或未正确认证，Skill 无法提供替代方案或自动修复能力。

2. 无实时反馈机制：作为静态参考指南，无法检测用户环境的实际配置状态（如认证是否有效、项目是否存在），命令输出示例可能与实际执行结果存在差异。

3. 功能边界受限：不包含 Rovo Dev AI 编码代理（rovodev）的深层能力说明，该功能标记为 Beta 且文档指向外部引用；亦不提供 Atlassian REST API 的直接调用能力，仅覆盖 CLI 封装层。

4. 平台锁定：完全绑定 Atlassian Cloud 生态，不兼容 Jira Data Center / Server 版本，亦不覆盖 Confluence、Bitbucket 等其他 Atlassian 产品的 CLI 操作（虽 acli 未来可能扩展，但当前文档未涉及）。

---

适合的目标群体

• DevOps / SRE 工程师：需将 Jira 操作集成到 CI/CD 流水线、自动化发布流程或运维脚本中
• 敏捷团队技术负责人：需批量管理 Sprint、看板，或自动化生成项目报告与度量数据
• Atlassian 组织管理员：需执行用户生命周期管理、安全审计、多站点配置等组织级运维
• 开发者效率工具爱好者：偏好命令行交互、追求比 Web UI 更高效的工作流操作
• 技术文档编写者：需生成一致的 Jira 操作示例、截图脚本或培训材料

---

使用风险与注意事项

性能风险：大规模 JQL 查询（如 project = * 配合 --paginate）可能触发 Atlassian API 速率限制，导致操作中断或账号临时受限。建议始终配合 --limit 测试查询范围。

认证管理风险：文档虽强调环境变量传参，但终端用户可能误将 API_TOKEN 写入 .bashrc 或脚本文件造成泄露。建议配合密钥管理工具（如 1Password CLI、AWS Secrets Manager）使用。

破坏性操作风险：delete、deactivate、archive 类命令不可逆或恢复成本极高。文档要求"每轮对话重新确认"，但用户若通过复制粘贴绕过 Agent 交互直接执行，将失去安全网保护。

版本兼容性风险：acli 工具本身迭代较快，Skill 文档基于特定版本编写。若 Atlassian 调整命令参数或移除废弃功能，文档示例可能失效。建议定期核对官方文档。