jr: A Jira CLI Tool Designed for AI Agents and Developers

jr is a Jira CLI tool designed specifically for AI agents and developers, aiming to address the pain points of traditional Jira clients' insufficient support for automation and programmability. Its core features include pure JSON output, structured errors, semantic exit codes, over 600 commands auto-generated from OpenAPI specifications, as well as AI-friendly workflow encapsulation, batch operations, jq filtering, and other functions to provide reliable support for machine interactions.

Traditional Jira clients are designed for human interaction, featuring interactive prompts, formatted outputs (tables, colors), etc., which are burdens for developers and AI agents pursuing automation. jr's design philosophy is the exact opposite: it prioritizes machine parsability—stdout always outputs pure JSON, stderr provides structured error information, and exit codes have clear semantics, ensuring AI agents can call and process results reliably.

• Pure JSON Output and Structured Errors: Success/failure outputs are all JSON; error messages include type and HTTP status code (e.g., {"error_type":"rate_limited","status":429,"retry_after":30} for rate limiting).
• Semantic Exit Codes: 0 = success, 2 = authentication failure, 3 = resource not found, 5 = rate limited,7=server error—facilitating automated process handling.
• 600+ Auto-Generated Commands: Generated from Jira OpenAPI specifications to ensure alignment with the latest APIs.
• Zero-Interaction Design: No prompts/confirmation boxes; outputs are predictable, suitable for automated environments.

jr provides encapsulated commands allowing AI agents to operate without knowing Jira internal IDs:

• Status transition: jr workflow move --issue PROJ-123 --to "In Progress" --assign me (using readable status names)
• Add comment: jr workflow comment --issue PROJ-123 --text "Fixed in latest deploy"
• Create issue: jr workflow create --project PROJ --type Bug --summary "Login broken" --priority High
• Others: Link issues, log work hours (2h 30m), sprint management (using names instead of IDs), etc.

• Batch Operations: Execute multiple commands via pipeline (e.g., echo '[{"command":"issue get",...}]' | jr batch), supporting jq filtering.
• jq Integration: The --jq parameter extracts required fields (e.g., jr issue get --issueIdOrKey PROJ-123 --jq '{key: .key, summary: .fields.summary}'), reducing token consumption.
• Watch Mode: jr watch --jql "project = PROJ" --interval 30s tracks changes in real time.
• Template System: Built-in templates like bug-report, supporting custom templates.
• Diff Tracking: jr diff --issue PROJ-123 --since 2h --field status monitors field changes.

• Operation Policies: Restrict allowed operations via configuration (e.g., {"allowed_operations": ["issue get", "search *", "workflow *"]}).
• Audit Logs: Record operations in JSONL format to meet compliance requirements.
• Raw API Access: jr raw GET /rest/api/3/myself handles edge cases.

• Skill files: Copy skill/jira-cli to Claude Code's configuration directory (cp -r skill/jira-cli ~/.claude/skills/).
• Agent instruction: Use