Atlassian Cli

atlassian-cli

安装

go install（推荐）

需要 Go 1.21+：

go install github.com/putcho01/atlassian-cli@latest

如果 $GOPATH/bin 不在你的 $PATH 中，请将以下内容添加到 shell 配置文件（如 ~/.zshrc）：

export PATH="$PATH:$(go env GOPATH)/bin"

从源码安装

git clone https://github.com/putcho01/atlassian-cli.git
cd atlassian-cli
go build -o atlassian-cli .

快速开始

Cloud（atlassian.net）

1. 创建 API Token

2. 设置环境变量：

export JIRA_URL=https://your-domain.atlassian.net
export [email protected]
export JIRA_API_TOKEN=your-api-token

3. 验证身份验证：

atlassian-cli jira myself

如需使用 Confluence，请设置以下附加变量：

export CONFLUENCE_URL=https://your-domain.atlassian.net/wiki
export [email protected]
export CONFLUENCE_API_TOKEN=your-api-token

Server/Data Center

export JIRA_URL=https://jira.example.com
export JIRA_PERSONAL_TOKEN=your-pat

如果未设置 JIRA_EMAIL，则会自动使用 Bearer（PAT）身份验证。

身份验证

支持两种身份验证方式：

Cloud - API Token（Basic Auth）

用于 Atlassian Cloud（*.atlassian.net）。使用你的电子邮件地址和 API Token 通过 Basic auth 进行身份验证。

变量	描述
JIRA_URL	Jira Cloud URL（例如 https://your-domain.atlassian.net）
JIRA_EMAIL	你的 Atlassian 账户电子邮件地址
JIRA_API_TOKEN	API Token
JIRA_DEFAULT_PROJECT	未提供 --project 时使用的默认项目键（可选）
CONFLUENCE_URL	Confluence Cloud URL（例如 https://your-domain.atlassian.net/wiki）
CONFLUENCE_EMAIL	你的 Atlassian 账户电子邮件地址
CONFLUENCE_API_TOKEN	API Token

Server/Data Center - Personal Access Token（Bearer）

用于自托管的 Jira/Confluence Server/DC。使用 PAT 通过 Bearer auth 进行身份验证。

变量	描述
JIRA_URL	Jira 基础 URL（例如 https://jira.example.com）
JIRA_PERSONAL_TOKEN	Personal Access Token
JIRA_DEFAULT_PROJECT	未提供 --project 时使用的默认项目键（可选）
CONFLUENCE_URL	Confluence 基础 URL
CONFLUENCE_PERSONAL_TOKEN	Personal Access Token

如果设置了 EMAIL，则使用 Basic auth（Cloud）；否则使用 Bearer auth（Server/DC）。

只需设置你所使用服务对应的变量。例如，如果你只使用 Jira，就不需要设置 Confluence 变量。

命令

Jira

# Authentication
atlassian-cli jira myself                # Show authenticated user

# Issues
atlassian-cli jira issue get PROJ-123    # Get issue (includes description)
atlassian-cli jira issue open PROJ-123   # Open issue in browser
atlassian-cli jira issue search "project = PROJ"       # Search issues via JQL
atlassian-cli jira issue search "project = PROJ" -i    # Interactive TUI picker (↑/↓ navigate, enter detail, o open, q quit)
atlassian-cli jira issue create --project PROJ --summary "New task"  # or omit --project if JIRA_DEFAULT_PROJECT is set
atlassian-cli jira issue update PROJ-123 --field summary="Updated summary"
atlassian-cli jira issue delete PROJ-123
atlassian-cli jira issue subtasks PROJ-123
atlassian-cli jira issue transition PROJ-123 "In Progress"

# Comments
atlassian-cli jira issue comment list PROJ-123
atlassian-cli jira issue comment add PROJ-123 --body "Looks good to me"

Confluence

# Pages
atlassian-cli confluence page get 12345          # Get page content
atlassian-cli confluence page create --space PROJ --title "New Page" --body "<p>Hello</p>"
atlassian-cli confluence page create --space PROJ --title "Child Page" --parent 12345 --body "<p>Child</p>"
atlassian-cli confluence page update 12345 --title "Updated Title" --body "<p>New content</p>"           # version auto-detected
atlassian-cli confluence page update 12345 --title "Updated Title" --body "<p>New content</p>" --version 3  # explicit version

# Labels
atlassian-cli confluence label list 12345
atlassian-cli confluence label add 12345 important,reviewed
atlassian-cli confluence label remove 12345 outdated

# Page Restrictions
atlassian-cli confluence restriction list 12345
atlassian-cli confluence restriction add 12345 --operation update --type user --name <account-id>
atlassian-cli confluence restriction remove 12345 --operation update --type user --name <account-id>

输出格式

所有命令都支持通过 --output / -o 标志指定三种输出格式：

# Default: human-readable table
atlassian-cli jira issue search "project = PROJ" -o table

# Machine-readable JSON
atlassian-cli jira issue search "project = PROJ" -o json

# GitHub-flavored Markdown (great for Claude Code)
atlassian-cli jira issue search "project = PROJ" -o markdown

HTML 转 Markdown

使用 -o markdown 时，HTML 内容（Jira 描述、Confluence 页面正文和评论）会自动转换为简洁的 GitHub 风格 Markdown。也会处理 Confluence 存储格式宏：

• 代码块（ac:structured-macro name="code"） -> 围栏代码块
• 提示框（note、info、warning、tip） -> 带标签的引用块
• 页面链接（ac:link） -> 强调文本
• 目录宏 -> 移除

MCP 服务

作为 MCP 服务启动，以便与 AI 助手集成：

atlassian-cli mcp-server

工具组筛选

使用 --tools 标志筛选可用工具：

# Only enable Jira issue and search tools
atlassian-cli mcp-server --tools jira_issue,jira_search

# Only enable Confluence tools
atlassian-cli mcp-server --tools confluence_page,confluence_label

可用工具组：

• jira_user - 用户身份验证
• jira_issue - 获取问题及其子任务
• jira_search - 使用 JQL 搜索问题
• jira_create - 创建问题
• jira_update - 更新问题
• jira_delete - 删除问题
• jira_transition - 转换问题状态，获取可用的状态转换
• confluence_page - 获取页面内容
• confluence_label - 标签管理
• confluence_restriction - 页面限制管理

Claude Code 集成

添加到 Claude Code MCP 设置中：

{
  "mcpServers": {
    "atlassian": {
      "command": "atlassian-cli",
      "args": ["mcp-server"],
      "env": {
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token",
        "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
        "CONFLUENCE_EMAIL": "[email protected]",
        "CONFLUENCE_API_TOKEN": "your-api-token"
      }
    }
  }
}

为什么不使用官方 ACLI？

Atlassian 提供官方 CLI（ACLI）和用于 AI 集成的远程 MCP 服务。此工具与它们的区别如下：

与 ACLI 对比

	atlassian-cli	ACLI
分发方式	单一二进制文件，无依赖项	需要安装软件包
身份验证	仅使用环境变量	交互式 acli auth login
对 CI/CD 的适用性	高 — 无需浏览器流程	有限 — 无头登录较繁琐
Server/DC 支持	支持（PAT 身份验证）	侧重 Cloud
目标用户	开发者、自动化系统、AI Agent	管理员、批量操作

与 Atlassian 远程 MCP 服务对比

Atlassian 的远程 MCP 服务于 2026 年 2 月正式发布，但也有一些取舍：

• 上下文占用大 — 会预先加载 73 个工具架构，在开始实际工作前就占用 40–50% 的上下文窗口
• 需要 OAuth — 基于浏览器的身份验证流程；不适用于无头环境或 CI/CD 环境
• 依赖网络 — 需要与 Atlassian 的远程服务建立出站连接

此工具的 --tools 标志让你只加载所需的组，从而最大限度地减少 AI Agent 的令牌用量。

适合选择此工具的场景

• 在 CI/CD 流水线 或自动化脚本中运行（仅通过环境变量进行身份验证）
• 使用同一接口操作 Server/Data Center 和 Cloud
• 在 AI Agent 中嵌入为 MCP 服务，且重视上下文效率

许可证

MIT