jira-cli

jira-cli

A non-interactive CLI for the Jira Cloud REST API v3, built for developers, agents, and CI/CD.

jira-cli is an unofficial tool, not affiliated with or endorsed by Atlassian. It is a separate project from ankitpokhrel/jira-cli, which installs a binary under the same name.

jira issue create --project PROJ --type Bug --summary "Login fails on Safari"
jira issue view PROJ-123 --json
jira issue move PROJ-123 "In Progress"
jira search "project = PROJ AND status = Open" --limit 10

Features

• Non-interactive — flags supply all input; every command runs unattended
• Pipe-safe — structured JSON output, correct exit codes, plain text when piped
• Agent-friendly — errors include codes, context, and fix suggestions so LLMs self-correct
• Agent SDLC loop — ready → claim → discover → close, blocker-aware and sprint-filtered
• Three credential sources — flags, environment variables, or stored profiles (keyring-backed)
• Markdown input — write descriptions and comments in Markdown; the CLI converts them to Atlassian Document Format
• JQL support — raw JQL via jira search or flag-based filtering via jira issue list
• Inline filtering — --jq flag extracts fields directly in the CLI
• Bulk export/import — round-trip issues to markdown files with YAML frontmatter
• Aliases — save frequently used commands as shortcuts

Install

Binary (macOS / Linux):

# Available platforms: darwin_arm64, darwin_amd64, linux_arm64, linux_amd64
gh release download --repo endgame-build/jira-cli --pattern '*darwin_arm64*'
tar xzf jira_*_darwin_arm64.tar.gz jira
sudo mv jira /usr/local/bin/

Or download from GitHub Releases.

From source (requires Go):

go install github.com/endgame-build/jira-cli/cmd/jira@latest

Quick Start

# Authenticate
jira auth login --instance mycompany.atlassian.net --user me@company.com --token <api-token>

# View an issue
jira issue view PROJ-123

# Create an issue
jira issue create --project PROJ --type Task --summary "Add retry logic" --description "Handle 429 responses"

# Edit an issue
jira issue edit PROJ-123 --add-labels urgent --priority High

# Transition an issue
jira issue move PROJ-123 "In Progress"

# Assign an issue
jira issue assign PROJ-123 "Jane Doe"

# Search with JQL
jira search "project = PROJ AND assignee = currentUser()" --json

# List my open issues
jira issue list --assignee @me

# Find work an agent can start on now, and claim it
jira agent ready --project PROJ --sprint active --json
jira agent claim PROJ-123

Commands

Issues

jira issue view <key-or-id>            # View issue details (--web to open in browser)
jira issue create                      # Create an issue (--project, --type, --summary required)
jira issue edit <key-or-id>            # Edit fields (--summary, --priority, --add-labels, etc.)
jira issue delete <key-or-id> --yes    # Delete an issue (requires --yes to confirm)
jira issue move <key-or-id> <status>   # Transition to a new status
jira issue assign <key-or-id> <user>   # Assign (display name, account ID, or @me)
jira issue assign <key-or-id> --unassign  # Remove assignee
jira issue list                        # List issues (--project, --assignee, --status, --sort)
jira issue transitions <key-or-id>     # Show available workflow transitions
jira issue export                      # Export issues to markdown (--project, --jql, --tree)
jira issue import <files...>           # Create/update issues from markdown (--dir, --force)
jira issue pull <files...>             # Reconcile status and assignee from Jira back into markdown
jira issue reconcile                   # Detect orphaned Jira issues (--dir, --epic, --project, --jql)

Agent Workflow

Commands for autonomous agents working a Jira backlog. jira agent prime prints the workflow context an agent needs; the rest move work through it.

jira agent prime                       # Print workflow context for agent injection (--full)
jira agent ready                       # Issues ready for work, no unresolved blockers
jira agent blocked                     # Issues blocked by unresolved dependencies
jira agent claim <key>                 # Assign to yourself and move to In Progress (--force)
jira agent close <key>                 # Move to Done (--reason, --suggest-next, --claim-next)
jira agent discover <parent-key>       # File newly found work against the current item
jira agent status                      # Ready, actionable, in-progress, blocked and done today

The loop these commands implement:

jira agent ready --project PROJ --sprint active --json   # find work
jira agent claim PROJ-123                                # assign + In Progress
# ...implement...
jira agent discover PROJ-123 --title "Retry on 429"      # file what you found
jira agent close PROJ-123 --reason "Shipped" --suggest-next

ready filters on --assignee @me, --unassigned, --type, --label, --priority, --component and --sprint active|future|<name>. It excludes anything blocked by an unresolved issue, so what it returns is what an agent can start on now.

Two details worth knowing. Blocked-ness is computed from is blocked by links whose target is not in the done status category, and claim/close resolve transitions by category rather than by status name — so both survive custom workflows. And status reports ready_count as every To Do issue in the project, while actionable_count is the subset with no blockers, which is what ready actually hands out; in_progress_count covers only your own issues, the rest are project-wide.

The command contracts are specified in docs/agent-sdlc-contracts.md, and test/e2e exercises the whole loop against a real sprint.

Sprints

jira sprint list                       # List sprints (--state active|future|closed, --board)
jira sprint active                     # Show the active sprint for a project
jira sprint add <key>...               # Move issues into a sprint (--sprint, defaults to active)

Sprints are found through the project's board. Both company-managed boards (which Jira reports as scrum) and team-managed ones (simple) are supported.

Search

jira search "<jql>"                    # Search with raw JQL (--limit, --fields)

Comments

jira comment list <issue-key>          # List comments on an issue
jira comment add <issue-key>           # Add a comment (--body or --body-file)
jira comment edit <issue-key> <id>     # Edit a comment
jira comment delete <issue-key> <id>   # Delete a comment (requires --yes)

Projects

jira project list                      # List all projects
jira project view <key-or-id>          # View project details

Users

jira user me                           # Show authenticated user
jira user search <query>               # Search for users by name or email

Schema

jira schema fields                     # List all fields
jira schema types                      # List issue types
jira schema statuses                   # List statuses
jira schema priorities                 # List priorities
jira schema labels                     # List labels
jira schema field-values               # Build field value mappings (--project, --output)

Config

jira config set <key> <value>          # Set a config value
jira config get <key>                  # Get a config value
jira config list                       # List all config values

Aliases

jira alias set <name> <command>        # Create or update an alias
jira alias list                        # List all aliases

Auth

jira auth login                        # Store credentials (--instance, --user, --token)
jira auth logout --yes                 # Remove stored credentials
jira auth status                       # Show current authentication (--check to fail on an invalid token)
jira auth switch <profile>             # Switch active profile

Meta

jira meta version                      # Show CLI version and build info
jira meta commands                     # List all commands (machine-readable)

Global Flags

Configuration

The CLI stores config at $XDG_CONFIG_HOME/jira-cli/config.toml (~/.config/jira-cli/ on Linux, ~/Library/Application Support/jira-cli/ on macOS). Set defaults to avoid repeating flags:

jira config set default.project PROJ
jira config set output.format json

CI/CD Usage

export JIRA_INSTANCE=mycompany.atlassian.net
export JIRA_USER=ci@company.com
export JIRA_TOKEN=$JIRA_API_TOKEN

jira issue create --project PROJ --type Bug --summary "Build failed" --json

Export / Import

Round-trip issues between Jira and local markdown files:

# Export all issues from a project
jira issue export --project PROJ --output-dir ./issues

# Export as a tree (epics become directories)
jira issue export --project PROJ --output-dir ./issues --tree

# Export specific custom fields only
jira issue export --project PROJ --fields "Team, Sprint, Story Points"

# Export with JQL
jira issue export --jql "project = PROJ AND status != Done" --output-dir ./issues

# Edit markdown files locally, then push changes back
jira issue import ./issues/PROJ/*.md

# Import from a directory
jira issue import --dir ./issues/PROJ

# Force import (skip conflict detection)
jira issue import --dir ./issues/PROJ --force

# Preview import without making changes
jira issue import --dir ./issues/PROJ --dry-run

Exported files use YAML frontmatter for metadata (key, type, status, priority, labels, assignee, custom fields) and Markdown body for the description. Files with temporary keys (PROJ-NEW-1) create new issues; files with real keys update existing ones.

Custom fields with object values (teams, options, users) are round-tripped via a .jira-field-values.json sidecar file that maps display names to Jira API objects. The sidecar is generated automatically during export and consumed during import.

Config-driven mapping (--map)

When your documents use their own frontmatter vocabulary (e.g. name, jira_key, initiative, stream) rather than the CLI's canonical keys, pass a declarative field-map and the CLI translates them, pushing content on import and reconciling status and assignee back on pull:

jira issue import ./epics/**/*.md --map ./jira-sync.yaml --force   # content: docs -> Jira
jira issue pull   ./epics/**/*.md --map ./jira-sync.yaml           # state: Jira -> docs (status, assignee)

--map is opt-in and backward compatible. See docs/config-driven-mapping.md and the annotated docs/jira-sync.example.yaml.

Reconcile

Detect issues that exist in Jira but have no corresponding markdown file:

# List orphaned issues under an epic
jira issue reconcile --dir ./issues --epic PROJ-10

# List orphans across a project
jira issue reconcile --dir ./issues --project PROJ

# List orphans with arbitrary JQL
jira issue reconcile --dir ./issues --jql "parent in (PROJ-10, PROJ-48) OR key in (PROJ-10, PROJ-48)"

# Close orphaned issues
jira issue reconcile --dir ./issues --epic PROJ-10 --action close --yes

# Delete orphaned issues
jira issue reconcile --dir ./issues --project PROJ --action delete --yes

Field Value Mappings

Build a sidecar mapping file from existing Jira issues (useful when starting without an export):

jira schema field-values --project PROJ --output .jira-field-values.json

Error Codes

Documentation

• Config-driven field mapping and the annotated example config
• Agent SDLC command contracts
• SPEC.md for the full command surface, CLAUDE.md for the architecture

Status

Active development against the Jira Cloud REST API v3. Jira Server and Data Center are unsupported. Releases before 1.0 can change flags and output between minor versions; pin a version in CI.

Contributing

Read CONTRIBUTING.md. It covers the setup, the conventional-commit format that drives releases, and the architecture rules new commands follow. Open an issue before writing code for anything larger than a bug fix.

Everyone taking part is expected to follow the Code of Conduct.

Support

See SUPPORT.md for where to file what. Questions about Jira itself belong in the Atlassian Community.

Security

Report vulnerabilities privately through GitHub's security advisories, never in a public issue. SECURITY.md covers the process and how jira-cli handles your API token.

License

Apache License 2.0. See LICENSE, NOTICE, and THIRD_PARTY_NOTICES.md for the licenses of the Go modules linked into the released binaries.

Trademarks

Jira and Atlassian are trademarks of Atlassian Pty Ltd. This project uses the names to describe what it is compatible with, and claims no affiliation with or endorsement by Atlassian.