atlassian-cli

Atlassian CLI (acli)

概述

Atlassian CLI（acli）提供对 Jira、Confluence 和其他 Atlassian 产品的命令行访问。**核心原则：**始终先检查身份验证，使用正确的命令结构，并充分利用批量操作。

适用场景

• 创建、搜索或更新 Jira 问题
• 管理冲刺、看板或项目
• 使用 Confluence 空间
• 对多个项目执行批量操作
• 生成 CSV/JSON 格式的报告
• 自动化 Atlassian 工作流

不适用场景：

• 更适合使用网页界面时（一次性的可视化任务）
• 已经可以使用 API 令牌/集成时

身份验证——始终是第一步

digraph auth_check {
    "User requests acli command" [shape=doublecircle];
    "Check auth status" [shape=box];
    "Authenticated?" [shape=diamond];
    "Run acli command" [shape=box];
    "Explain: acli auth login" [shape=box];

    "User requests acli command" -> "Check auth status";
    "Check auth status" -> "Authenticated?";
    "Authenticated?" -> "Run acli command" [label="yes"];
    "Authenticated?" -> "Explain: acli auth login" [label="no"];
}

执行任何 acli 操作之前：

# Check if authenticated
acli auth status

# If not authenticated, login first
acli auth login

命令结构

格式：acli <product> <entity> <action> [flags]

不要使用带 --action 标志的旧式语法。

# ❌ WRONG - old syntax that doesn't work
acli jira --action getIssueList --jql "..."

# ✅ CORRECT - modern syntax
acli jira workitem search --jql "..."

快速参考

常见产品

• auth - 身份验证管理
• jira - Jira Cloud 命令
• confluence - Confluence Cloud 命令
• admin - 管理操作

Jira 实体与操作

实体	常见操作	示例
workitem	search、create、create-bulk、edit、view、transition、assign、delete	acli jira workitem search --jql "project = TEAM"
project	list、view、create、update、delete、archive	acli jira project list
sprint	create、update、view、delete、list-workitems	acli jira sprint view 123
board	search、get、create、delete、list-sprints	acli jira board list-sprints --board 42
workitem comment	create、list、update、delete	acli jira workitem comment create --key KEY-1 --comment "text"

Confluence 实体

实体	操作	示例
space	list、view、create、update、archive、restore	acli confluence space list

批量操作

使用 JQL、筛选条件或键列表来操作多个项目：

# Edit multiple issues with JQL
acli jira workitem edit --jql "project = MOBILE AND status = 'In Review'" --assignee "[email protected]" --yes

# Transition multiple issues
acli jira workitem transition --jql "assignee = currentUser() AND status = 'To Do'" --status "In Progress" --yes

# Search with filter
acli jira workitem search --filter 10001 --csv

# Multiple keys
acli jira workitem assign --key "KEY-1,KEY-2,KEY-3" --assignee "@me"

批量标志：

• --jql - 用于多个项目的 JQL 查询
• --filter - 已保存搜索的筛选器 ID
• --key - 以逗号分隔的问题键
• --yes / -y - 跳过确认提示
• --ignore-errors - 出错时继续（适用于批量操作）

输出格式

根据使用场景选择合适的输出格式：

# CSV for spreadsheets
acli jira workitem search --jql "sprint = 42" --csv

# JSON for scripts/automation
acli jira workitem search --jql "project = API" --json

# Web browser for viewing
acli jira workitem view KEY-123 --web

# Custom fields (default includes key, summary, status, etc.)
acli jira workitem search --jql "..." --fields "key,summary,assignee,priority"

常见标志：

• --csv - CSV 输出（不要使用 --outputFormat 999）
• --json - JSON 输出
• --web - 在网页浏览器中打开
• --fields - 指定要显示的字段（不要使用 --columns）
• --count - 仅显示数量
• --paginate - 获取所有结果

批量创建

用于创建多个相似问题：

# Generate JSON template
acli jira workitem create --generate-json

# Create from JSON file
acli jira workitem create --from-json workitem.json

# Bulk create multiple issues
acli jira workitem create-bulk

# Use file for description
acli jira workitem create --summary "Bug title" --project API --type Bug --from-file description.txt

# Use editor for interactive creation
acli jira workitem create --editor

如果可以使用 create-bulk 或 --from-json，就不要编写包含 10 条单独创建命令的 Bash 循环。

常见 JQL 模式

# Current user's issues
--jql "assignee = currentUser()"

# Specific project and status
--jql "project = TEAM AND status = 'In Progress'"

# Multiple criteria
--jql "project = API AND type = Bug AND status != Done"

# Sprint issues
--jql "project = TEAM AND sprint = 42"

# Recent updates
--jql "project = WEBAPP AND updated >= -7d"

常见错误

错误	错误原因	正确做法
跳过身份验证检查	未通过身份验证时命令会失败	始终先运行 acli auth status
使用 --action 标志	旧语法不适用于现代版 acli	使用 acli <product> <entity> <action>
--outputFormat 999	标志错误	使用 --csv
--columns 参数	该参数不存在	使用 --fields
用 Bash 循环创建	效率低，且已有内置功能	使用 create-bulk、--from-json
逐个编辑	批量操作速度慢	使用 --jql 或 --filter 配合 edit/transition
凭空编造命令	浪费时间	运行 acli <product> <entity> --help 进行验证

危险信号——停下并检查技能

这些迹象表明你即将犯错：

• 跳过身份验证检查
• 在命令中使用 --action
• 为批量操作编写 bash 循环
• 建议使用 --outputFormat 而不是 --csv
• 使用 --columns 而不是 --fields
• 未查看 --help 就编造命令名称
• “旧语法可能仍然可用”
• “他们可能已经通过身份验证了”
• “bash 循环比内置命令更灵活”

以上任何一种情况都意味着：停下，重新阅读此技能，并使用正确的语法。

工作流模式

digraph workflow {
    "acli request" [shape=doublecircle];
    "Check auth status" [shape=box];
    "Authenticated?" [shape=diamond];
    "Run acli auth login" [shape=box];
    "Verify command with --help" [shape=box];
    "Check for batch operation?" [shape=diamond];
    "Use --jql/--filter/--key" [shape=box];
    "Single operation" [shape=box];
    "Choose output format" [shape=box];
    "Execute command" [shape=box];

    "acli request" -> "Check auth status";
    "Check auth status" -> "Authenticated?";
    "Authenticated?" -> "Run acli auth login" [label="no"];
    "Run acli auth login" -> "Verify command with --help";
    "Authenticated?" -> "Verify command with --help" [label="yes"];
    "Verify command with --help" -> "Check for batch operation?";
    "Check for batch operation?" -> "Use --jql/--filter/--key" [label="multiple items"];
    "Check for batch operation?" -> "Single operation" [label="single item"];
    "Use --jql/--filter/--key" -> "Choose output format";
    "Single operation" -> "Choose output format";
    "Choose output format" -> "Execute command";
}

工作流示例

Sprint 报告

# 1. Check auth
acli auth status

# 2. Search sprint issues with CSV output
acli jira workitem search --jql "project = TEAM AND sprint = 42" --fields "key,summary,status,assignee" --csv > sprint-report.csv

批量更新状态

# 1. Check auth
acli auth status

# 2. Verify issues first
acli jira workitem search --jql "project = MOBILE AND status = 'In Review'" --count

# 3. Transition all
acli jira workitem transition --jql "project = MOBILE AND status = 'In Review'" --status "Done" --yes

# 4. Assign all
acli jira workitem assign --jql "project = MOBILE AND status = Done" --assignee "[email protected]" --yes

创建多个 Issue

# 1. Check auth
acli auth status

# 2. Generate template
acli jira workitem create --generate-json > template.json

# 3. Edit template.json with your data

# 4. Create from template (repeat for each)
acli jira workitem create --from-json issue1.json
acli jira workitem create --from-json issue2.json

# OR use create-bulk
acli jira workitem create-bulk

获取帮助

# Top-level help
acli --help

# Product help
acli jira --help

# Entity help
acli jira workitem --help

# Action help
acli jira workitem search --help

如有疑问，请查看 --help，确认确切的标志和语法。