内容
# jira_cli
`jira_cli` 是一个面向 Jira Server/Data Center 的本地 Jira 工具，同时提供 Cobra CLI 和 MCP stdio server。它适合把企业内网 Jira 接入 Codex、Claude Code、OpenCode 等 AI 编程工具，也可以作为日常命令行使用。
核心能力包括多账号配置、token 或 Basic Auth、只读账号、JQL 搜索、任务查询、字段发现、备注、流转、分配、附件、任务关联、创建/编辑元数据、任务创建和更新。
## 开源定位
`jira_cli` 不追求替代所有 Jira 客户端，它优先解决三类场景：
- 企业内网 Jira Server/Data Center 需要一个本地 stdio MCP server。
- AI agent 需要可控地读取 Jira，并通过只读模式避免误写。
- Windows 用户需要低摩擦安装，同时保留 Linux/macOS 的普通二进制分发。
如果你只需要官方 Jira Cloud OAuth 集成，Atlassian Rovo MCP Server 可能更合适。如果你只需要成熟的通用 Jira 命令行客户端，已有项目也很多。`jira_cli` 的差异点是本地 MCP、Server/Data Center 兼容、账号级只读策略和 AI agent 友好的输出。
## 快速体验 CLI
`jira_cli` 没有内置 Jira 地址。先配置服务器和一种认证方式：
```powershell
jira_cli set base-url https://jira.example.com --global
jira_cli set token <token> --global
jira_cli user me
jira_cli issue search "project = PROJ ORDER BY updated DESC"
```
Jira 使用用户名密码认证时，用 `set auth <username> <password>` 替代 `set token`。凭证会写入 `.jira_cli/config.json`，不要提交这个文件。
## 快速体验 MCP
先保存账号，再把 MCP server 配给你的 AI 工具：
```powershell
jira_cli set base-url https://jira.example.com --name work --global
jira_cli set token <token> --name work --global
jira_cli set readonly on --name work --global
jira_cli mcp --user=work
```
stdio MCP 配置示例：
```json
{
"mcpServers": {
"jira": {
"command": "jira_cli",
"args": ["mcp", "--user=work"]
}
}
}
```
只读模式下，CLI 写命令会被隐藏或拒绝，MCP 写工具不会注册。需要开放创建和更新任务时，再显式关闭只读，并确认 `JIRA_CREATE_OPEN` 没有设为 `false`。
## 方案边界
| 方案 | 更适合 | `jira_cli` 的区别 |
| --- | --- | --- |
| Atlassian Rovo MCP Server | Jira Cloud、官方 OAuth、Atlassian 托管入口 | 本地 stdio、适合内网 Jira Server/Data Center |
| 通用 Jira CLI | 纯命令行任务管理、成熟生态和脚本集成 | 同时提供 MCP server，面向 AI agent 工作流 |
| 直接调用 Jira REST API | 自定义系统集成 | 封装认证、配置、只读策略、字段元数据和输出整理 |
## 安装和构建
Requires Go 1.26.3 or later.
从源码安装：
```powershell
go install github.com/wishesl/jira_cli@latest
```
本地构建：
```powershell
go build -o bin\jira_cli.exe .
```
Linux/macOS 可使用不带 `.exe` 的输出路径：
```bash
go build -o bin/jira_cli .
```
发布包会提供 Windows、Linux、macOS 的 amd64/arm64 构建。Windows 包额外包含 `install.bat` 和 `install-global.ps1`，用于安装命令和 Codex Skill。
## 兼容性
客户端面向暴露 Jira REST API v2 的 Jira 安装，主要按 Jira Server/Data Center 风格端点测试。它支持 Bearer token 和 Basic Auth。Jira Cloud 的认证和 REST 行为可能不同，用于自动化前请先在自己的实例上验证。
## 打包和全局安装
一键打包 Windows 版本：
```powershell
.\scripts\package.ps1
```
脚本会生成：
```text
dist\jira_cli\jira_cli.exe
dist\jira_cli\README.md
dist\jira_cli\LICENSE
dist\jira_cli\SKILL.md
dist\jira_cli\install-global.ps1
dist\jira_cli\install.bat
dist\jira_cli.zip
```
从打包目录安装到当前用户 PATH，可以双击：
```powershell
.\dist\jira_cli\install.bat
```
也可以用 PowerShell 安装：
```powershell
powershell -ExecutionPolicy Bypass -File .\dist\jira_cli\install-global.ps1
```
## 配置文件
CLI 读取配置文件中的配置文件，首先是 `./.jira_cli/config.json`，然后是 `~/.jira_cli/config.json`。写入时，会先更新现有的本地配置文件，然后是现有的全局配置文件；如果两者都不存在，则会创建本地配置文件。使用 `--local` 或 `--global` 来显式选择。
```powershell
# 默认配置文件：root
jira_cli set base-url https://jira.example.com --global
jira_cli set token <token> --global
# 基本认证替换配置文件中的 token
jira_cli set auth <username> <password> --global
# 命名配置文件
jira_cli set base-url https://jira-work.example.com --name work
jira_cli set token <token> --name work
# 项目本地配置文件
jira_cli set base-url https://jira-project.example.com --local
jira_cli set token <token> --local
# 查看已配置的配置文件名称
jira_cli set accounts
```
单个配置文件时，命令会自动使用它。多个配置文件时，可以显式选择：
```powershell
jira_cli --user=work user me
```
连接值按以下顺序解析：
```text
已保存的配置文件 -> 环境变量 -> 命令行标志
```
支持的环境变量有：
| 变量 | 用途 |
| --- | --- |
| `JIRA_BASEURL` | Jira 基本 URL |
| `JIRA_TOKEN` | Bearer token |
| `JIRA_USERNAME` | 基本认证用户名 |
| `JIRA_PASSWORD` | 基本认证密码 |
| `JIRA_READONLY` | 强制只读模式为 `true` |
对于一次性命令，可以使用 `--token` 或 `--username` 和 `--password`。
## 输出和错误
命令会自动选择其正常响应格式。失败时，`jira_cli` 默认会在标准错误中写入可读的 `error: ...` 消息。使用 `--output json` 时，其他程序需要结构化的错误对象：
```powershell
jira_cli --output json issue get PROJ-123
```
JSON 输出保留可读字符，如 `<` 和 `&`，而不是将其转义为 Unicode 序列。
## CLI 用法
```powershell
# 账户和用户操作
jira_cli user me
jira_cli user search xiake --max-results 20
# 任务查找和 JQL
jira_cli issue get PROJ-123
jira_cli issue search "project = PROJ ORDER BY updated DESC"
jira_cli issue search "assignee = currentUser()" --keys
jira_cli set search-columns key,summary,fixVersions
jira_cli issue search "project = PROJ" # 使用保存的表格列
jira_cli issue search "project = PROJ" --columns summary,key,customfield_11203
jira_cli field list --query "release"
jira_cli field list --custom-only
# 评论、分配和流转
jira_cli issue comment PROJ-123 "Investigating the issue"
jira_cli issue assign PROJ-123 xiake
jira_cli issue transitions PROJ-123
jira_cli issue do-transition PROJ-123 21 --comment "Resolved"
# 从 JSON 文件创建和更新字段
jira_cli issue create PROJ Task --fields @fields.json
jira_cli issue update PROJ-123 --fields @fields.json
jira_cli issue update PROJ-123 --update @update.json
# 查询 Jira 必需字段和分页长允许值列表
jira_cli issue create-meta PROJ --issue-type Task
jira_cli issue create-meta-values PROJ Task priority --query High
jira_cli issue edit-meta PROJ-123
jira_cli issue edit-meta-values PROJ-123 components --max-results 20
# 附件
jira_cli attachment list PROJ-123
jira_cli attachment upload PROJ-123 .\report.txt
jira_cli attachment download <attachment-content-url> .\report.txt
jira_cli attachment delete <attachment-id>
# 任务链接
jira_cli issue link-types
jira_cli issue link PROJ-123 PROJ-124 --type Relates
jira_cli issue unlink <link-id>
```
### 任务获取视图
`issue get <key>` 默认返回一个紧凑的工作上下文 JSON 文档。它包括任务描述、简化的附件元数据和下载 URL、任务链接、`fix_versions` 作为版本名称，以及最近的三条评论和总评论数。仅传输的字段（如 `self`、头像 URL 和附件缩略图）被省略。
```powershell
# 紧凑的摘要
jira_cli issue get PROJ-123 --view summary
# 调用者请求的精确 Jira 字段
jira_cli issue get PROJ-123 --fields summary,customfield_11203
# 旧版完整的 Jira 任务响应
jira_cli issue get PROJ-123 --full
# 单行 Markdown 摘要表格
jira_cli issue get PROJ-123 --output table
```
对于 `issue create` 和 `issue update`，`--fields @file.json` 和 `--update @file.json` 从文件中加载 JSON 对象，避免了 Windows 上的 shell 引号问题。
`set search-columns <columns>` 保存每个帐户的搜索表格列的默认设置。`issue search --columns <columns>` 覆盖它用于单个命令，而 `set search-columns default` 恢复内置的 `key,status,priority,assignee,summary` 顺序。列接受 Jira REST 字段 ID，如 `fixVersions` 和 `customfield_11203`；它们仅限于表格，并且仅请求所选的 Jira 字段。
使用 `set search-columns show` 检查有效的列以及它们来自配置文件还是内置默认值。`field list` 显示可见的 Jira 字段 ID、显示名称、类型、数组项目类型和自定义字段标记；使用 `--query` 或 `--custom-only` 来缩小结果范围。
### 帮助语言
帮助输出默认为中文。保存英文为常用帮助语言：
```powershell
jira_cli set help-language en
```
使用 `zh` 切换回中文。偏好仅存储在用户全局配置中，仅影响 `-h` 和 `--help`。为单个命令覆盖它而不保存偏好：
```powershell
jira_cli --lang en issue search -h
jira_cli issue get --lang zh -h
```
`api get` 对相对 Jira API 路径执行身份验证的 GET 请求：
```powershell
jira_cli api get /rest/api/2/issue/PROJ-123
```
## 只读账户
按配置文件设置只读模式：
```powershell
jira_cli set readonly on --name work
```
只读模式下，CLI 写命令将被隐藏或在运行时拒绝。对于 MCP，写工具不会注册。`JIRA_READONLY=true` 覆盖已保存的配置文件以获取当前进程。
## MCP 服务器
通过标准输入/输出启动服务器：
```powershell
jira_cli mcp --user=work
```
对于使用_stdio服务器定义的MCP客户端，重用已保存的配置文件，以便不必将令牌复制到客户端配置文件中：
```json
{
"mcpServers": {
"jira": {
"command": "jira_cli",
"args": ["mcp", "--user=work"]
}
}
}
```
使用 `jira_cli.exe` 的绝对路径，当它不在 `PATH` 上时。
`mcp` 还会在当前工作目录中加载一个 `.env` 文件。除了上面的连接变量外，它还接受：
| 变量 | 用途 |
| --- | --- |
| `JIRA_CREATE_OPEN` | 设置为 `false` 以省略创建/更新 MCP 工具 |
| `JIRA_DISABLE_DISCLAIMER` | 设置为 `true` 以停止向注释添加 AI 公告 |
| `JIRA_CREATE_SUMMARY_MAX` | 最大创建摘要长度 |
| `JIRA_CREATE_DESCRIPTION_MAX` | 最大创建描述长度 |
| `JIRA_CREATE_FIELDS_MAX_BYTES` | 创建字段的最大 JSON 大小 |
MCP 服务器为用户、JQL、问题、转换、元数据、附件、问题链接类型和相对 API GET 请求公开读取工具。写入工具涵盖评论、转换、分配、附件、问题链接，并且在启用时，还包括问题创建和更新。
## 开发
```powershell
gofmt -w cmd internal pkg main.go
go test ./...
go vet ./...
go build -o bin\jira_cli.exe .
```
不要提交 `.jira_cli/config.json`、令牌、密码、生成的可执行文件或本地代理/编辑器工件。
## 许可证
MIT
