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 地址。先配置服务器和一种认证方式：

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 工具：

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 配置示例：

{
  "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.

从源码安装：

go install github.com/wishesl/jira_cli@latest

本地构建：

go build -o bin\jira_cli.exe .

Linux/macOS 可使用不带 .exe 的输出路径：

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 版本：

.\scripts\package.ps1

脚本会生成：

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，可以双击：

.\dist\jira_cli\install.bat

也可以用 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.

# 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:

jira_cli --user=work user me

Connection values are resolved in this order:

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:

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

# 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.

# 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:

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:

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:

jira_cli api get /rest/api/2/issue/PROJ-123

Read-Only Accounts

Set read-only mode per profile:

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:

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:

{
  "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

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