jira4claude

A minimal Jira CLI designed for AI coding agents.

Why?

AI coding agents run in non-interactive contexts where prompts hang and complex output is hard to parse. This CLI is designed from first principles for that environment:

• Never prompts - missing required flags produce errors, not interactive prompts
• Markdown output - valid GFM readable by both humans and AI
• JSON mode - --json flag for programmatic field extraction
• Minimal scope - ~11 commands covering what agents actually need
• Unix composable - line-oriented output works with fzf, grep, jq
• Semantic exit codes - handle errors programmatically without parsing messages
• Predictable structure - same input always produces same output format

Quick Start

# Install
brew install fwojciec/tap/j4c

# Configure credentials (~/.netrc)
echo "machine yourcompany.atlassian.net
  login your-email@example.com
  password your-api-token" >> ~/.netrc

# Initialize project config
j4c init --server=https://yourcompany.atlassian.net --project=PROJ

# Start working
j4c issue list --assignee=me
j4c issue view PROJ-123

Get an API token from Atlassian Account Settings.

Output Modes

Markdown (Default)

All output is valid GitHub-Flavored Markdown:

j4c issue view J4C-81

# J4C-81: Implement linked issues display

**Type:** Task
**Status:** Done
**Priority:** Medium
**Assignee:** Filip Wojciechowski

## Context

Add linked issues section to issue view output...

## Linked Issues

**is blocked by:**
- **J4C-74** [Done] Inject Converter into CLI IssueContext
- **J4C-76** [Done] Add warning propagation

**blocks:**
- **J4C-78** [Done] Rename adf package

[View in Jira](https://company.atlassian.net/browse/J4C-81)

Issue lists are line-oriented for easy piping:

j4c issue list --limit=3

- **J4C-110** [To Do] [P2] Standardize issue list item format
- **J4C-95** [To Do] [P2] Investigate epic support
- **J4C-66** [To Do] [P2] Create Homebrew tap

JSON Mode

Add --json for programmatic access:

j4c issue view PROJ-123 --json

{
  "key": "PROJ-123",
  "summary": "Fix login timeout",
  "status": "In Progress",
  "type": "Bug",
  "priority": "High",
  "assignee": "Alice",
  "url": "https://company.atlassian.net/browse/PROJ-123"
}

Unix Composability

The markdown format is designed for composition with standard tools:

# Pretty rendering
j4c issue view J4C-123 | glow

# Interactive selection
j4c issue list | fzf

# Search issues
j4c issue list | grep "bug"

# Extract keys programmatically
j4c issue list --json | jq -r '.[].key'

# Batch transition
j4c issue list --status="In Progress" --json | \
  jq -r '.[].key' | \
  xargs -I{} j4c issue transition {} --status="Done"

Markdown and Jira

Jira stores content in Atlassian Document Format (ADF), not markdown. This CLI handles conversion automatically:

• Input: Write descriptions and comments in GitHub-Flavored Markdown
• Storage: CLI converts to ADF when sending to Jira API
• Output: CLI converts ADF back to markdown when displaying

Unsupported elements (like embedded images) generate warnings but don't block operations.

Commands

Issue Operations

j4c issue view PROJ-123                    # View single issue
j4c issue list --project=PROJ              # List issues
j4c issue list --status="In Progress"      # Filter by status
j4c issue list --assignee=me               # Filter by assignee
j4c issue list --labels=urgent,backend     # Filter by labels
j4c issue list --jql="priority = High"     # Raw JQL query
j4c issue ready                            # Issues with no blockers
j4c issue create --summary="Title"         # Create issue
j4c issue update PROJ-123 --priority=High  # Update issue
j4c issue transitions PROJ-123             # List available transitions
j4c issue transition PROJ-123 --status="Done"
j4c issue assign PROJ-123 --account-id=... # Assign issue
j4c issue comment PROJ-123 --body="Done"   # Add comment

Link Operations

j4c link create PROJ-1 Blocks PROJ-2       # PROJ-1 blocks PROJ-2
j4c link list PROJ-123                     # List links
j4c link delete PROJ-1 PROJ-2              # Remove link

Configuration

j4c init --server=https://... --project=PROJ

Creates .jira4claude.yaml in current directory.

Exit Codes

Semantic exit codes for programmatic error handling:

Code	Meaning
0	Success
1	Validation error (invalid input)
2	Authentication failed
3	Permission denied
4	Resource not found
5	Conflict (e.g., duplicate)
6	Rate limit exceeded
7	Internal/unexpected error

Error Messages

Errors include actionable context so AI agents can self-correct without additional API calls:

The error shows which transition was attempted, why it failed, and what transitions are available - enabling immediate retry with the correct value.

Installation

Homebrew (macOS/Linux)

brew install fwojciec/tap/j4c

From Source

go install github.com/fwojciec/jira4claude/cmd/j4c@latest

From Releases

Download binaries from the releases page.

License

MIT