temet-jira 0.3.0

Comprehensive Jira API client and CLI tool

temet-jira

A comprehensive Jira API client and CLI tool for interacting with Jira Cloud instances. Built for AI agents and automation workflows — retrieve tickets, create rich ADF content, and analyze workflow state durations.

Table of Contents

• Features
• Quick Start
  • Installation
  • Configuration
  • First Commands
• CLI Commands
• MCP Server
• Claude Code Integration
• Python API
• Development
• Requirements

Features

• Agent-First Design — Enable AI agents to retrieve tickets, parse requirements, and create implementation plans
• Jira API Client — Python and CLI interface to Jira Cloud REST API v3
• Structured Data Export — Export issues in JSON, JSONL, CSV formats optimized for agent processing
• Document Builder — Programmatically create ADF-formatted issues and epics with proper structure
• Workflow Analysis — Analyze state durations and bottlenecks for retrospectives
• Epic Management — Retrieve epics with children, filter by sprint, group by assignee/status
• JQL Support — Advanced filtering for complex queries and batch operations
• Claude Code Integration — Skills, slash commands, and an MCP server for AI-assisted workflows

Quick Start

Installation

Recommended: install as a global tool with uv

uv tool install temet-jira

Alternative: pipx

pipx install temet-jira

Verify:

temet-jira --help

Configuration

Run the interactive setup wizard:

temet-jira setup

This guides you through:

1. Your Jira URL (e.g. https://your-company.atlassian.net)
2. Your email address
3. API token — generate one at https://id.atlassian.com/manage-profile/security/api-tokens
4. Optional default project key

Configuration is saved to ~/.config/temet-jira/config.yaml.

Alternative: environment variables

export JIRA_BASE_URL="https://your-company.atlassian.net"
export JIRA_USERNAME="[e-mail]"
export JIRA_API_TOKEN="your-api-token"
export JIRA_DEFAULT_PROJECT="PROJ"          # optional
export JIRA_DEFAULT_FORMAT="json"           # optional: table (default), json, jsonl, csv

Check your current configuration at any time:

temet-jira config show

Multiple Jira instances (named profiles)

Each profile is a separate Jira instance in ~/.config/temet-jira/config.yaml:

temet-jira config profile add work          # setup wizard for the 'work' profile
temet-jira config profile list
temet-jira --profile work search "project = PROJ"

Bind a folder to a profile so cd-ing in auto-selects the right instance — run this inside the repo:

temet-jira config project set profile work   # writes ./.temet-jira.yaml
temet-jira config project set project PROJ    # optional non-sensitive default
temet-jira config project show

Profile selection precedence (highest first): --profile flag → a per-project ./.temet-jira.yaml (profile:) → TEMET_JIRA_PROFILE → default_profile → default. A committed .temet-jira.yaml can also set non-sensitive defaults (project, component, default_format, max_results) — credentials are rejected by config project and always stay in the named profile, so the file is safe to commit. (config global … is the explicit-scope alias for writing the active profile; the bare config set … is shorthand for it.)

First Commands

# Get issue details
temet-jira get PROJ-123

# Search for issues using JQL
temet-jira search "project = PROJ AND status = 'In Progress'"

# List available issue types for a project
temet-jira types --project PROJ

# Create a task
temet-jira create --project PROJ --type Task --summary "Fix login bug"

# Export to CSV
temet-jira export --project PROJ --format csv -o tickets.csv

CLI Commands

Command	Description
setup	Interactive setup wizard
config	View and manage configuration (show, get, set, unset, path, edit)
get	Get details of a Jira issue
search	Search for issues using JQL
types	List available issue types for a project
create	Create a new issue with ADF formatting
update	Update issue fields or transition status
comment	Add a comment to an issue
transitions	Show available status transitions for an issue
epics	List all epics in a project
epic-details	Get epic details with child issues
export	Export issues with filtering (JSON, JSONL, CSV, table)
analyze	Analyze workflow state durations

Examples:

temet-jira get PROJ-123                                  # Issue details
temet-jira search "assignee = currentUser()"            # JQL search
temet-jira types --project PROJ                         # Available issue types
temet-jira create --project PROJ --type Story \
    --summary "New feature" --priority High             # Create issue
temet-jira update PROJ-123 --status "Done"              # Transition status
temet-jira comment PROJ-123 "Deployed to staging"       # Add comment
temet-jira export --project PROJ --format jsonl \
    -o issues.jsonl                                     # Export (streaming)
temet-jira analyze state-durations issues.json          # Workflow analysis

Output formats: table (console default), json, jsonl (streaming, best for large datasets), csv

MCP Server

temet-jira ships with a built-in MCP server (temet-jira-mcp) compatible with any MCP-enabled client: Claude Code, Cursor, Windsurf, VS Code Copilot, Zed, and others.

Guided setup:

temet-jira mcp add

This scans your system for existing config files, asks where you want to install, and prints the exact JSON snippet to paste — including the right format for your client.

List available tools:

temet-jira mcp tools

Exposed tools:

Tool	Description
get_issue	Fetch a single issue by key (supports expand: transitions, changelog)
search_issues	Search with JQL, returns paginated results
create_issue	Create a new issue with optional description, labels, priority
update_issue	Update fields or transition status
add_comment	Add a comment to an issue
get_transitions	List available status transitions for an issue
transition_issue	Move an issue to a new status
get_epics	List epics in a project
get_issue_types	List available issue types for a project

Manual config (if you prefer): run temet-jira mcp add and choose "Other" for a generic snippet you can adapt to any client.

Claude Code Integration

Slash commands are available in .claude/commands/jira/ — use with the /jira: prefix in Claude Code:

Command	Description
/jira:get PROJ-123	Get ticket details
/jira:search "JQL query"	Search with JQL
/jira:create	Create an issue
/jira:update PROJ-123	Update an issue
/jira:comment PROJ-123 "message"	Add a comment
/jira:export	Export issues
/jira:epics	List epics
/jira:epic-details PROJ-123	Epic with children
/jira:transitions PROJ-123	Show transitions

Skills in .claude/skills/ provide reference documentation for Claude:

Skill	Description
jira-api	Jira REST API v3 documentation, endpoints, JQL patterns
jira-builders	CLI usage guide and best practices
build-jira-document-format	ADF builder patterns
work-with-adf	Atlassian Document Format creation

Python API

from temet_jira import JiraClient, IssueBuilder, EpicBuilder

# Fetch an issue
client = JiraClient()
issue = client.get_issue("PROJ-123")

# Create a structured issue with ADF content
builder = IssueBuilder(title="New feature", story_points=8)
builder.add_description("Feature description")
builder.add_acceptance_criteria(["Criteria 1", "Criteria 2"])

client.create_issue({
    "project": {"key": "PROJ"},
    "summary": "New feature",
    "issuetype": {"name": "Story"},
    "description": builder.build(),
})

Also available: JiraDocumentBuilder (raw ADF builder), SubtaskBuilder, StateDurationAnalyzer.

Development

# Clone and install dev dependencies
git clone https://github.com/temet-ai/temet-jira.git
cd temet-jira
uv sync --extra dev

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=temet_jira

# Lint and type check
uv run ruff check src/ tests/
uv run mypy src/

# After code changes, rebuild the installed binary
uv build && uv tool install . --force --refresh-package temet-jira

Project Structure

temet-jira/
├── src/temet_jira/          # Main package
│   ├── client.py            # JiraClient API
│   ├── formatter.py         # Document builders (legacy entry point)
│   ├── cli.py               # CLI commands
│   ├── mcp_server.py        # MCP server
│   ├── document/            # ADF document builder
│   └── analysis/            # State duration analysis
├── .claude/
│   ├── commands/            # Slash commands for Claude Code
│   └── skills/              # Reference skills
├── tests/                   # Test suite
└── pyproject.toml

Requirements

• Python 3.11+
• uv or pipx for installation
• Jira Cloud (REST API v3)
• Valid Jira API token

License

MIT

Support

• Open an issue at https://github.com/temet-ai/temet-jira/issues