Content
# 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
```
## Configure Profiles
The CLI reads profiles from `./.jira_cli/config.json` first, then
`~/.jira_cli/config.json`. Writes update an existing local configuration first,
then an existing global configuration; when neither exists, a local
configuration is created. Use `--local` or `--global` to choose explicitly.
```powershell
# Default profile: root
jira_cli set base-url https://jira.example.com --global
jira_cli set token <token> --global
# Basic authentication replaces a token for that profile
jira_cli set auth <username> <password> --global
# Named profile
jira_cli set base-url https://jira-work.example.com --name work
jira_cli set token <token> --name work
# Project-local profile
jira_cli set base-url https://jira-project.example.com --local
jira_cli set token <token> --local
# Inspect configured profile names
jira_cli set accounts
```
With a single configured profile, commands use it automatically. With multiple
profiles, select one explicitly:
```powershell
jira_cli --user=work user me
```
Connection values are resolved in this order:
```text
saved profile -> environment variables -> command-line flags
```
Supported environment variables are:
| Variable | Purpose |
| --- | --- |
| `JIRA_BASEURL` | Jira base URL |
| `JIRA_TOKEN` | Bearer token |
| `JIRA_USERNAME` | Basic-auth username |
| `JIRA_PASSWORD` | Basic-auth password |
| `JIRA_READONLY` | Force read-only mode with `true` |
Use either `--token` or `--username` with `--password` for one-off commands.
When both authentication modes are supplied, the token is used.
## Output and Errors
Commands select their normal response format automatically. On failure,
`jira_cli` writes a readable `error: ...` message to standard error by default.
Use `--output json` when another program needs a structured error object:
```powershell
jira_cli --output json issue get PROJ-123
```
JSON output keeps readable characters such as `<` and `&` intact rather than
escaping them as Unicode sequences.
## CLI Usage
```powershell
# Account and user operations
jira_cli user me
jira_cli user search xiake --max-results 20
# Issue lookup and 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" # Uses the saved table columns
jira_cli issue search "project = PROJ" --columns summary,key,customfield_11203
jira_cli field list --query "release"
jira_cli field list --custom-only
# Comments, assignment, and transitions
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"
# Create and update fields from a JSON file
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
# Query Jira-required fields and paginate long allowed-value lists
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
# Attachments
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>
# Issue links
jira_cli issue link-types
jira_cli issue link PROJ-123 PROJ-124 --type Relates
jira_cli issue unlink <link-id>
```
### Issue Get Views
`issue get <key>` returns a compact work-context JSON document by default. It
includes the issue description, simplified attachment metadata and download
URLs, issue links, `fix_versions` as version names, and the three most recent
comments together with the total comment count. Transport-only fields such as
`self`, avatar URLs, and attachment thumbnails are omitted.
```powershell
# Compact summary only
jira_cli issue get PROJ-123 --view summary
# Exact Jira fields requested by the caller
jira_cli issue get PROJ-123 --fields summary,customfield_11203
# Legacy full Jira issue response
jira_cli issue get PROJ-123 --full
# Single-row Markdown summary table
jira_cli issue get PROJ-123 --output table
```
For `issue create` and `issue update`, `--fields @file.json` and
`--update @file.json` load a JSON object from a file, which avoids shell
quoting issues on Windows.
`set search-columns <columns>` saves a per-account default for search table
columns. `issue search --columns <columns>` overrides it for one command, and
`set search-columns default` restores the built-in `key,status,priority,assignee,summary`
order. Columns accept Jira REST field IDs such as `fixVersions` and
`customfield_11203`; they are table-only and request only the selected Jira
fields.
Use `set search-columns show` to inspect the effective columns and whether they
come from the profile or the built-in default. `field list` shows visible Jira
field IDs, display names, types, array item types, and custom-field markers;
use `--query` or `--custom-only` to narrow the result.
### Help Language
Help output defaults to Chinese. Save English as the common help language with:
```powershell
jira_cli set help-language en
```
Use `zh` to switch it back. The preference is stored only in the user-global
configuration and affects `-h` and `--help` only. Override it for one command
without saving a preference:
```powershell
jira_cli --lang en issue search -h
jira_cli issue get --lang zh -h
```
`api get` performs an authenticated GET against a relative Jira API path only:
```powershell
jira_cli api get /rest/api/2/issue/PROJ-123
```
## Read-Only Accounts
Set read-only mode per profile:
```powershell
jira_cli set readonly on --name work
```
Read-only mode removes CLI write commands from help and rejects them at runtime.
For MCP, write tools are not registered. `JIRA_READONLY=true` overrides
the saved profile for the current process.
## MCP Server
Start the server over standard input/output:
```powershell
jira_cli mcp --user=work
```
For MCP clients that use a stdio server definition, reuse a saved profile so
tokens do not need to be copied into the client configuration:
```json
{
"mcpServers": {
"jira": {
"command": "jira_cli",
"args": ["mcp", "--user=work"]
}
}
}
```
Use the absolute path to `jira_cli.exe` when it is not installed on `PATH`.
`mcp` also loads a `.env` file in the current working directory. In addition to
the connection variables above, it accepts:
| Variable | Purpose |
| --- | --- |
| `JIRA_CREATE_OPEN` | Set to `false` to omit create/update MCP tools |
| `JIRA_DISABLE_DISCLAIMER` | Set to `true` to stop adding the AI notice to comments |
| `JIRA_CREATE_SUMMARY_MAX` | Maximum create summary length |
| `JIRA_CREATE_DESCRIPTION_MAX` | Maximum create description length |
| `JIRA_CREATE_FIELDS_MAX_BYTES` | Maximum JSON size for create fields |
The MCP server exposes read tools for users, JQL, issues, transitions,
metadata, attachments, issue-link types, and relative API GET requests. Write
tools cover comments, transitions, assignment, attachments, issue links, and,
when enabled, issue creation and updates.
## Development
```powershell
gofmt -w cmd internal pkg main.go
go test ./...
go vet ./...
go build -o bin\jira_cli.exe .
```
Do not commit `.jira_cli/config.json`, tokens, passwords, generated
executables, or local agent/editor artifacts.
## License
MIT
