budjira

Your CLI Pal for Jira

budjira (pronounced "buddy-ra") is your CLI buddy for Jira. It provides efficient, user-friendly command-line access to Jira Cloud with features designed for both developers and AI-assisted project management.

Note: budjira is designed for Jira Cloud only and does not support Jira Server or Data Center. For legacy on-premise installations, consider using go-jira or planning your Cloud migration.

✨ Features

🔗 Multi-Connection: Manage multiple Jira instances and projects
🎯 Context-Aware: Name-based connection management with environment variable and CLI override support
🔄 Auto-Update: Automatic update checks with GitHub Releases integration
🤖 AI-Friendly: Designed for seamless AI-assisted workflows with built-in usage prompt generation
🎨 Rich Output: Beautiful, colorful terminal output with tables and formatting
🔍 Search & Filter: Powerful JQL-based ticket search with filter options
✏️ Create Issues: Interactive and non-interactive issue creation
📋 Definition of Ready: Customizable templates for Story, Bug, Task with validation
🔄 Update Issues: Transition status, update fields, manage labels, delete issues
🎯 Epic Management: Link stories to epics and view epic progress
💬 Comment Management: Add comments to issues without time tracking
⏱️ Time Tracking: Comprehensive worklog management and time estimates
🎼 Tempo Integration: Full support for Tempo Timesheets API for enterprise time tracking
📊 JSON Output: Machine-readable JSON format for automation and integration with other tools

📦 Installation

Quick Install (Recommended)

Install with a single curl command:

curl -LsSf https://raw.githubusercontent.com/cdds-ab/budjira/master/install.sh | sh

This will:

Install uv if not already present
Clone the budjira repository to ~/.local/share/budjira
Install dependencies
Create a symlink in ~/.local/bin/budjira

Make sure ~/.local/bin is in your PATH:

export PATH="$HOME/.local/bin:$PATH"

Manual Installation

# Clone the repository
git clone https://github.com/cdds-ab/budjira.git
cd budjira

# Install dependencies
uv sync

# Run budjira
uv run budjira --help

# Or create a symlink
ln -s "$(pwd)/.venv/bin/budjira" ~/.local/bin/budjira

Update

To update to the latest version:

curl -LsSf https://raw.githubusercontent.com/cdds-ab/budjira/master/install.sh | sh

Or manually:

cd ~/.local/share/budjira
git pull
uv sync

Shell Completion

budjira supports tab completion for bash, zsh, and fish shells.

Enable completion (one-time setup):

budjira --install-completion

This automatically configures your shell's completion system. Restart your shell or open a new terminal for changes to take effect.

Test completion:

budjira <TAB>          # Shows available commands
budjira connect <TAB>  # Shows connect subcommands

Manual completion (if auto-install doesn't work):

# Bash
budjira --show-completion bash > ~/.local/share/bash-completion/completions/budjira

# Zsh
budjira --show-completion zsh > ~/.zsh/completions/_budjira

# Fish
budjira --show-completion fish > ~/.config/fish/completions/budjira.fish

🚀 Quick Start

1. Connect to Jira

# Create a new connection for the current project
budjira connect

# You'll be prompted for:
# - Jira URL (e.g., https://your-company.atlassian.net)
# - Email
# - API Token (create one at https://id.atlassian.com/manage-profile/security/api-tokens)
# - Default project key

2. Manage Connections

# List all connections
budjira connect list

# Show connection details
budjira connect show [NAME]

# Test connection
budjira connect test [NAME]

# Set default connection
budjira connect use NAME

# Show active connection
budjira connect current

# Remove a connection
budjira connect remove [NAME]

3. Search for Issues

# Search with JQL query
budjira search "project = PROJ AND status = 'In Progress'"

# Search with filters
budjira search --status "In Progress" --assignee currentUser()
budjira search --project PROJ --type Bug --max 100

# Use specific connection
budjira search --connection my-connection --status Done

4. View Issue Details

Get comprehensive information about a specific issue including description, comments, time tracking, attachments, and more.

# Show full issue details
budjira show PROJ-123

# Show issue from specific connection
budjira show PROJ-456 --connection my-connection

Displays:

Summary and description (with Markdown rendering)
Issue type, status, priority, assignee, reporter
Epic information (if linked to an epic)
Time tracking (original estimate, remaining, time spent)
Labels and components
Comments with timestamps
Attachments with file sizes
Creation and update timestamps

5. Create Issues

# Interactive mode (default)
budjira create issue "Fix login bug"

# Non-interactive with all details
budjira create issue "Fix bug" --type Bug --priority High --no-interactive

# With description and labels
budjira create issue "Add feature" \
  --type Story \
  --description "Detailed description" \
  --assignee jdoe \
  --label feature --label frontend \
  --no-interactive

# Link to epic during creation (one-step workflow)
budjira create issue "User authentication" --type Story --epic PROJ-100

# Create multiple stories for same epic (efficient bulk creation)
budjira create issue "Story 1" --type Story --epic PROJ-100 --no-interactive
budjira create issue "Story 2" --type Story --epic PROJ-100 --no-interactive
budjira create issue "Story 3" --type Story --epic PROJ-100 --no-interactive

Epic Linking:

Use --epic PROJ-100 to link issue to epic during creation
Eliminates need for separate update step
Perfect for creating multiple stories for same epic
Works in both interactive and non-interactive modes

6. Definition of Ready (DoR) Templates

budjira supports customizable templates for different issue types to ensure consistent quality.

# List all DoR templates
budjira dor list

# View template for specific issue type
budjira dor show Story

# Edit template in your editor
budjira dor edit Story

# Validate template structure
budjira dor validate Story

Default Templates:

Story: Context, User Story, Acceptance Criteria (all required)
Bug: Steps to Reproduce, Expected Behavior, Actual Behavior, Environment
Task: Description, Acceptance Criteria

Interactive Creation with DoR: When creating issues interactively, budjira will offer to open your editor with the DoR template:

$ budjira create issue "Add user login"
Issue type: Story
Use DoR template for Story? [Y/n]: y
# Opens editor with:
## Context
# Why do we need this?

## User Story
As a [role]
I want to [action]
So that [benefit]

## Acceptance Criteria
- [ ]

Configuration:

Templates stored in ~/.config/budjira/dor-templates.toml
Validation level: strict (block), warn (allow), or off
Skip validation with --skip-dor flag

7. Update Issues

# Transition status
budjira issue update PROJ-123 --status "In Progress"

# Assign to current user
budjira issue update PROJ-123 --assignee currentUser()

# Multiple updates at once
budjira issue update PROJ-123 \
  --status Done \
  --priority Low \
  --add-label completed

# Link to epic
budjira issue update PROJ-123 --epic PROJ-100

# Show available transitions
budjira issue transitions PROJ-123

# Delete an issue (with confirmation)
budjira issue delete PROJ-123

# Delete without confirmation
budjira issue delete PROJ-123 --force

# Delete issue and its subtasks
budjira issue delete PROJ-123 --delete-subtasks

8. View Epic Progress

# Show epic with all child stories (table format)
budjira epic show PROJ-100

# JSON output with time tracking for automation/reporting
budjira --format json epic show PROJ-100

JSON Output Example:

{
  "epic": {
    "key": "PROJ-100",
    "summary": "Project Infrastructure",
    "status": "In Progress",
    "assignee": "John Doe",
    "priority": "High",
    "issue_type": "Epic",
    "url": "https://your-company.atlassian.net/browse/PROJ-100",
    "timetracking": {
      "originalEstimateSeconds": 72000,
      "remainingEstimateSeconds": 36000,
      "timeSpentSeconds": 36000,
      "originalEstimate": "20h",
      "remainingEstimate": "10h",
      "timeSpent": "10h"
    }
  },
  "stories": [
    {
      "key": "PROJ-101",
      "summary": "Setup CI/CD Pipeline",
      "status": "Done",
      "assignee": "Jane Smith",
      "issue_type": "Story",
      "priority": "High",
      "url": "https://your-company.atlassian.net/browse/PROJ-101",
      "timetracking": {
        "originalEstimateSeconds": 14400,
        "timeSpentSeconds": 14400,
        "originalEstimate": "4h",
        "timeSpent": "4h"
      }
    }
  ],
  "progress": {
    "total_issues": 5,
    "done_issues": 2,
    "in_progress_issues": 1,
    "todo_issues": 3,
    "progress_percent": 40
  }
}

Use Cases:

Project Reporting: Generate HTML/PDF reports with epic progress
Dashboard Integration: Feed data into custom dashboards
Time Analysis: Analyze time tracking data for effort estimation
Automation: Use in CI/CD pipelines or scripts

9. Check for Updates

budjira automatically checks for updates every 24 hours and notifies you when a new version is available.

# Check for updates manually
budjira update --check

# Update to latest version (interactive)
budjira update

# Force update check (bypass cache)
budjira update --check --force

Troubleshooting: GitHub API Rate Limits

If you see 403 Client Error: rate limit exceeded when checking for updates, you need to authenticate with GitHub:

# Option 1: Set GitHub Personal Access Token (no scopes needed)
export GITHUB_TOKEN=ghp_your_token_here

# Option 2: Use GitHub CLI token (if gh is installed)
export GH_TOKEN=$(gh auth token)

# Make it permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export GITHUB_TOKEN=ghp_your_token_here' >> ~/.bashrc
source ~/.bashrc

Create a token: Go to https://github.com/settings/tokens (no scopes required for public repos)

Why? Unauthenticated requests are limited to 60/hour. Authenticated requests get 5,000/hour.

10. AI Integration

Generate comprehensive usage guides for AI assistants.

# Generate AI usage prompt
budjira ai usage-prompt

# Copy to clipboard (Linux with xclip)
budjira ai usage-prompt | xclip -selection clipboard

# Save to file
budjira ai usage-prompt > budjira-guide.md

The generated prompt includes:

Complete command reference with examples
Connection management workflows
Search and create patterns
Error handling guidance
Common use cases for AI assistants

Time Tracking

budjira provides comprehensive time tracking capabilities including worklog management and time estimates.

# Add work log entry
budjira worklog add PROJ-123 2h --comment "Fixed authentication bug"
budjira worklog add PROJ-123 1h30m --comment "Code review"

# Log work with specific start time
budjira worklog add PROJ-123 3h --started "2025-10-24 14:00" --comment "Implemented feature"
budjira worklog add PROJ-123 2h --started "yesterday" --comment "Bug fixing"

# List all worklogs for an issue (shows worklog IDs)
budjira worklog list PROJ-123

# Delete a worklog entry
budjira worklog delete PROJ-123 12345
budjira worklog delete PROJ-123 12345 --force   # Skip confirmation

# Set time estimates when creating issues
budjira create issue "Add login feature" \
  --type Story \
  --original-estimate 8h \
  --remaining-estimate 8h

# Update time estimates
budjira issue update PROJ-123 --original-estimate 10h --remaining-estimate 5h

# Log work and update remaining estimate in one command
budjira issue update PROJ-123 --log-work 2h --work-comment "Implemented API endpoint"

Supported Time Formats:

Hours: 2h, 8h
Minutes: 30m, 45m
Combined: 2h30m, 1h45m

Supported Datetime Formats (for --started):

ISO format: 2025-10-25T14:30:00, 2025-10-25 14:30
Date only: 2025-10-25 (time defaults to 00:00)
Relative: today, yesterday

Add Comments

Add comments to Jira issues without logging time (unlike worklogs which combine comments with time tracking).

# Quick single-line comment
budjira comment add PROJ-123 "Deployed to production"

# Multi-line comment via editor
budjira comment add PROJ-123 --editor

# Editor opens automatically if no text provided
budjira comment add PROJ-123

# Use specific connection
budjira comment add PROJ-123 "Comment text" --connection my-connection

Use Cases:

Status updates without time tracking
Analysis results and findings
Documentation links
Deployment notifications
Code review feedback

Editor Support:

Opens your preferred editor (from $EDITOR environment variable, defaults to vim)
Supports markdown formatting
Multi-line content for detailed updates

Tempo Timesheets Integration

For enterprise teams using Tempo Timesheets, budjira provides full API integration for advanced time tracking and billing.

Setup:

# Configure Tempo for your connection
budjira connect tempo-setup

# Create a Tempo API token at: Tempo → Settings → API Integration → Tokens

Usage:

# Log work via Tempo
budjira tempo log PROJ-123 2h --comment "Sizing analysis"
budjira tempo log PROJ-456 3h30m --started "yesterday" --comment "Client meeting"

# Log work with specific datetime
budjira tempo log PROJ-123 2h --started "2025-10-24 14:00" --comment "Development"

# List Tempo worklogs
budjira tempo worklogs PROJ-123                    # For specific issue
budjira tempo worklogs --from 2025-10-01 --to 2025-10-31  # Date range
budjira tempo worklogs --max 50                    # Limit results

# Update existing worklog (preserve ID and audit trail)
budjira tempo update-worklog 12345 --time-spent 3h
budjira tempo update-worklog 12345 --started "2025-10-28" --comment "Updated"
budjira tempo update-worklog 12345 --force        # Skip confirmation

# Delete worklog entry
budjira tempo delete-worklog 12345
budjira tempo delete-worklog 12345 --force        # Skip confirmation

# List Tempo accounts (for billing)
budjira tempo accounts

Features:

✅ Full Tempo Cloud API support
✅ Worklog creation with time tracking
✅ Worklog listing with filters
✅ Worklog updates (time, date, comment) with automatic issue ID resolution
✅ Worklog deletion
✅ Tempo Accounts listing for billing
✅ Automatic connection detection
✅ Secure token storage
✅ Cross-instance workflow support (planning + booking Jira with Tempo)

When to use Tempo vs. Standard Jira:

Use budjira tempo commands when your organization uses Tempo for time tracking
Use budjira worklog commands for standard Jira time tracking
Tempo integration is optional and requires a separate API token

JSON Output Format

budjira supports JSON output for automation and integration with other tools (e.g., reporting systems, data analysis).

Usage:

# Global --format flag (works with all list-based commands)
budjira --format json tempo worklogs --from 2025-10-01 --to 2025-10-31

# Output to file for processing
budjira --format json tempo worklogs PROJ-123 > worklogs.json

# Pipe to jq for analysis
budjira --format json tempo worklogs --from 2025-10-01 | jq '.worklogs[].time_spent_seconds' | jq -s add

Example JSON Output:

{
  "total": 2,
  "worklogs": [
    {
      "id": 619,
      "issue_key": "PRD-1",
      "epic_key": "PRD-1",
      "epic_name": "budjira Development",
      "time_spent_seconds": 900,
      "time_spent_display": "15m",
      "date": "2025-10-26",
      "author_account_id": "712020:5...",
      "author_display_name": "Fred Thiele",
      "description": "Testing budjira Tempo integration"
    }
  ]
}

Features:

✅ Machine-readable JSON output
✅ Epic information included (epic_key, epic_name)
✅ Performance mode with --no-epic flag
✅ Works with all list-based commands
✅ Pipes and redirection friendly

Performance Note: Epic information requires additional Jira API calls. Use --no-epic for faster output:

budjira --format json tempo worklogs --no-epic

🔧 Configuration

budjira follows the XDG Base Directory specification and stores configuration in:

~/.config/budjira/
├── connections.toml      # Connection definitions
├── credentials/          # Secure credential storage
├── dor-templates.toml   # Definition of Ready templates
├── cache/               # Optional issue cache
├── logs/                # Per-context log files
└── config.toml          # Global settings

🚧 Coming Soon

The following features are currently in development:

Additional Planned Features

Comment Management: List, edit, and delete comments (add already available)
Attachment Support: Upload and download attachments
Sprint Management: View and manage sprints
Dashboard Commands: View personalized dashboards

🎯 Use Cases

For Developers

Quick Ticket Lookup: Search and view issues without opening a browser
Time Logging: Track time spent on tasks directly from terminal
Workflow Integration: Integrate Jira operations into shell scripts and CI/CD pipelines

For AI-Assisted Project Management

Synchronization Bridge: Keep project documentation and Jira in sync
Automated Updates: Let AI assistants update Jira based on local project changes
Quality Checks: Validate that Jira accurately represents project state
Batch Operations: Process multiple issues efficiently via scripts

🤝 Contributing

Contributions are welcome! Please check out our contributing guidelines (coming soon).

Development Setup

# Clone the repository
git clone https://github.com/cdds-ab/budjira.git
cd budjira

# Install dependencies with development extras
uv sync --all-extras

# Install pre-commit hooks
uv run pre-commit install

# Run tests
uv run pytest

# Run linting
uv run ruff check .

# Run type checking
uv run mypy budjira

Code Quality

budjira maintains high code quality standards:

✅ Ruff: Fast linting and formatting
✅ MyPy: Strict type checking
✅ Bandit: Security vulnerability scanning
✅ 70% minimum test coverage: Enforced by pre-commit hooks
✅ CI/Pre-commit Consistency: Single source of truth via pre-commit action
✅ Conventional Commits: Semantic versioning via commit messages

📚 Documentation

CLAUDE.md - Comprehensive development guide
API Documentation (coming soon)
Examples (coming soon)

🔐 Security

⚠️ IMPORTANT: This repository is PUBLIC.

For Users

Credentials are stored securely using system keyring where available
API tokens are never logged or displayed in output
Security scanning via Bandit in CI/CD pipeline
Regular dependency updates via Dependabot

For Contributors

Automatic Issue Data Sanitization (GitHub Action):

All issues are automatically scanned for sensitive data (emails, customer names, URLs)
Warnings posted immediately if patterns detected
Always use dummy data in issues: user@example.com, acme-corp, company.atlassian.net
Review PR diffs before submitting to ensure no sensitive information

If you find sensitive data in existing issues, please report it immediately or submit a PR to anonymize it.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with Typer for CLI magic
Powered by jira-python for Jira integration
Fast package management by uv
Beautiful output via Rich

🐛 Issues & Support

Found a bug? Have a feature request?

Open an issue
Check existing issues

🗺️ Roadmap

Implemented ✅

Planned 📋

Made with ❤️ by cdds-ab

Name		Name	Last commit message	Last commit date
Latest commit History 176 Commits
.claude		.claude
.github/workflows		.github/workflows
budjira		budjira
images		images
scripts		scripts
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

budjira

✨ Features

📦 Installation

Quick Install (Recommended)

Manual Installation

Update

Shell Completion

🚀 Quick Start

1. Connect to Jira

2. Manage Connections

3. Search for Issues

4. View Issue Details

5. Create Issues

6. Definition of Ready (DoR) Templates

7. Update Issues

8. View Epic Progress

9. Check for Updates

10. AI Integration

Time Tracking

Add Comments

Tempo Timesheets Integration

JSON Output Format

🔧 Configuration

🚧 Coming Soon

Additional Planned Features

🎯 Use Cases

For Developers

For AI-Assisted Project Management

🤝 Contributing

Development Setup

Code Quality

📚 Documentation

🔐 Security

For Users

For Contributors

📄 License

🙏 Acknowledgments

🐛 Issues & Support

🗺️ Roadmap

Implemented ✅

Planned 📋

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 60

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages