jira-cli

Drive Jira issue-tracking workflows from your terminal — built for coding agents.

jira-cli lets coding agents (Claude Code and others) — and humans — read, search and maintain Jira issues from the command line: fetch issues, run JQL searches, create/edit/assign issues, move them through workflow transitions, manage comments, and log work. It speaks to both Jira Cloud (REST v3) and Data Center / Server (REST v2), returns agent-friendly JSON with structured errors, and ships a companion Skill that teaches an agent how to use it. Write commands support --dry-run, and destructive ones require --yes.

📖 Documentation site: https://angelmsger.github.io/jira-cli/

Features

• Cloud & Data Center — one flavor-agnostic client; the backend is detected automatically, and the ADF-vs-plain-text body asymmetry is bridged so both flavors take and return plain text.
• Agent-friendly — JSON output by default, structured errors with exit codes and recovery hints, {items, next, has_more} pagination, and --fields projection so an agent spends minimal context.
• Read & write — fetch issues, JQL search (raw or composed from flags); create, edit and assign issues; workflow transitions with name resolution; read, post, edit and delete comments; log, correct and delete worklogs with remaining-estimate control. Every write supports --dry-run; destructive commands need --yes.
• Time tracking — worklog speaks Jira's own units ("3h 20m") and normalizes --started into the colon-free instant the API demands. worklog search --since 7d reconstructs a person's week across issues within a bounded, half-open window.
• Flexible configuration — CLI flags, environment variables, a .env file, a YAML config file, or an interactive wizard; secrets stored in the OS keychain.
• Companion Skill — a jira Skill, embedded in the binary, that guides coding agents through the CLI.

Installation

Install the CLI with npm, then take two short steps to finish setup — deploy the companion Skill, then (optionally) enable shell completion.

1. Install the CLI — npm (recommended)

npm install -g @angelmsger/jira-cli

npm downloads the prebuilt binary for your platform, verifies its SHA-256 checksum, and keeps upgrades one npm update -g @angelmsger/jira-cli away.

go install github.com/angelmsger/jira-cli/cmd/jira-cli@latest   # go 1.24+
make install                                                                # from a source checkout

Or download a prebuilt binary from the Releases page. The full installation guide covers every method.

2. Deploy the companion Skill

The jira Skill is embedded in the binary; it teaches your coding agent (Claude Code, Codex, Cursor, Agents (shared), Gemini CLI, GitHub Copilot, OpenCode, Continue, Windsurf, Grok Build, Pi, Kilo Code, and Roo Code) how to drive the CLI. skill install probes for installed agents and installs into each one found:

jira-cli skill install            # auto-detect; install for each agent found
jira-cli skill install --agent codex
jira-cli skill status             # compare loaded, installed, embedded versions
jira-cli skill uninstall          # remove it again

After upgrading the CLI, re-run skill install and reload the agent context. Details, including the npx skills workflow, are in docs/installation.md.

3. Enable shell completion (optional)

jira-cli completes subcommands, enum flag values and live project keys. Load the completion script for your shell once:

source <(jira-cli completion bash)                       # bash, current shell
jira-cli completion zsh > "${fpath[1]}/_jira-cli"   # zsh, persistent

fish, PowerShell and persistent setup are covered in docs/installation.md.

Quick start

jira-cli config init --pretty   # interactive TUI setup (recommended for humans)
jira-cli doctor                 # verify configuration and connectivity

jira-cli issue search --project ENG --assignee me
jira-cli issue get PROJ-123
jira-cli issue transition PROJ-123 --to "In Progress"
jira-cli comment add PROJ-123 --body "Deployed to staging."
jira-cli worklog add PROJ-123 --time-spent "3h 20m" --comment "Traced the retry loop"
jira-cli worklog search --since 7d

Configuration

Settings resolve in precedence order (highest first): CLI flags → environment variables (JIRA_*) → .env → ~/.angelmsger/jira/config.yaml → defaults. See .env.example and docs/installation.md. Secrets are stored in the OS keychain. If Windows Credential Manager is unavailable, the fallback is encrypted with per-user DPAPI; macOS/Linux retain the 0600 fallback. Secrets are never written to the config file.

This is the beginning of the README. Read the rest at the original. Read the full README ↗