Pure JSON stdout. Structured errors on stderr. Semantic exit codes. 600+ auto-generated commands from the Jira OpenAPI spec. Zero prompts, zero interactivity — just pipe and parse.

Table of Contents

🔍 Features · 📦 Install · 🚀 Quick Start · ⚡ Key Commands · 🤖 Agent Integration · 🔒 Security · 🛠 Development · 📄 License

🔍 Features

Self-Describing jr schema discovers every resource and verb at runtime — no hardcoded command lists	Token-Efficient --preset, --fields, and --jq stack to shrink 10K tokens down to 50	Workflow Commands Plain-English ops — no transition IDs, account IDs, or sprint IDs required
Batch Operations Run N operations in one process from a JSON array — single exit code	Real-Time Watch NDJSON event stream with initial, created, updated, removed events	Issue Templates Built-in + custom templates for structured issue creation with variables

↑ Back to top

📦 Install

brew install sofq/tap/jr          # macOS / Linux
npm install -g jira-jr            # Node
pip install jira-jr               # Python
scoop bucket add sofq https://github.com/sofq/scoop-bucket && scoop install jr  # Windows
go install github.com/sofq/jira-cli@latest                                      # Go

↑ Back to top

🚀 Quick Start

# Configure credentials
jr configure --base-url https://yourorg.atlassian.net --token YOUR_API_TOKEN --username your@email.com

# Verify the connection
jr configure --test

# Fetch an issue with agent-optimized output
jr issue get --issueIdOrKey PROJ-123 --preset agent

Tip

Use jr schema to discover all available commands, and jr schema issue get to see the full flag reference for any operation.

↑ Back to top

⚡ Key Commands

Workflow — plain English, no Jira internals

jr workflow move --issue PROJ-123 --to "In Progress" --assign me
jr workflow comment --issue PROJ-123 --text "Fixed in latest deploy"
jr workflow create --project PROJ --type Bug --summary "Login broken" --priority High
jr workflow link --from PROJ-1 --to PROJ-2 --type blocks
jr workflow log-work --issue PROJ-123 --time "2h 30m"
jr workflow sprint --issue PROJ-123 --to "Sprint 5"

Search — JQL with token-efficient output

jr search search-and-reconsile-issues-using-jql \
  --jql "project = PROJ AND status = 'In Progress'" \
  --fields "key,summary,status" \
  --jq '[.issues[] | {key, summary: .fields.summary}]'

Batch — N operations, one process

echo '[
  {"command":"issue get","args":{"issueIdOrKey":"PROJ-1"},"jq":".key"},
  {"command":"issue get","args":{"issueIdOrKey":"PROJ-2"},"jq":".key"}
]' | jr batch

Watch — real-time NDJSON stream

jr watch --jql "project = PROJ" --interval 30s --max-events 10

Templates — structured issue creation

jr template apply bug-report --project PROJ --var summary="Login broken" --var severity=High
jr template create my-template --from PROJ-123

Built-in templates: bug-report, story, task, epic, subtask, spike.

Diff — structured changelog

jr diff --issue PROJ-123 --since 2h --field status

Raw — escape hatch for any endpoint

jr raw GET /rest/api/3/myself
jr raw POST /rest/api/3/search/jql --body '{"jql":"project=PROJ"}'

Error contract

{"error_type":"rate_limited","status":429,"retry_after":30}

Exit	Meaning	Agent action
0	OK	Parse stdout
1	General error	Check error message
2	Auth failed	Re-authenticate
3	Not found	Check issue key
4	Validation	Fix request fields
5	Rate limited	Wait retry_after
6	Conflict	Resolve and retry
7	Server error	Retry with backoff

↑ Back to top

🤖 Agent Integration

Claude Code skill (included)

cp -r skill/jira-cli ~/.claude/skills/    # global install

Any agent

Add to your agent's system instructions:

Use `jr` for all Jira operations. Output is always JSON.
Use `jr schema` to discover commands. Use --jq to reduce tokens.

Note

See skill/jira-cli/SKILL.md for the full agent integration guide with patterns, error handling, and token optimization strategies.

↑ Back to top

🔒 Security

Operation policies — restrict per profile with glob patterns:

{
  "allowed_operations": ["issue get", "search *", "workflow *"]
}

Audit logging — JSONL to ~/.config/jr/audit.log via --audit flag or per-profile config.

Batch limits — default 50, override with --max-batch N.

↑ Back to top

🛠 Development

make generate    # regenerate commands from OpenAPI spec
make build       # compile binary
make test        # run tests with coverage
make lint        # run golangci-lint

Note

Commands in cmd/generated/ are auto-generated from spec/jira-v3.json. Run make generate after spec updates.

↑ Back to top

📄 License

Apache 2.0 © 2026 sofq