jiracli

README

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.

Other install methods — go install, source build, prebuilt binary

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.

Commands

Command	Purpose
issue get	fetch one issue (key or URL) with normalized fields
issue search	JQL search, raw or built from --project/--assignee/--status/...
issue create / edit	create an issue; update summary/description/priority/labels
issue assign	change or clear the assignee (--to / --unassign)
issue transitions / issue transition	discover and run workflow transitions
project list / project get	browse projects
project components / versions / issuetypes / statuses	discover a project's valid field values: components, versions, creatable issue types, workflow statuses
priority list / label list	instance-wide priorities and labels (label listing is Jira Cloud only)
field list / field options	generic create-screen field discovery, incl. a custom select field's allowed values per project + issue type context
comment list / add / update / delete	read, post, edit and remove comments; delete needs --yes
worklog list / add / update / delete	read and maintain an issue's worklogs; --adjust-estimate controls the remaining estimate; delete needs --yes
worklog search	one user's worklogs across issues inside a bounded --since / --from+--to window
whoami	print the user the credentials authenticate as
user resolve / user me	resolve a user selector to the identifier assignee flags accept
skill install / skill uninstall	deploy or remove the embedded companion Skill (Claude Code, Codex, Cursor, Agents, Gemini, GitHub Copilot, OpenCode, Continue, Windsurf, Grok Build, Pi, Kilo Code, Roo Code)
config get-contexts / use-context / delete-context	manage multiple named servers; deleting a context keeps a credential another context still uses
config / auth / doctor / version	setup and diagnostics

In the default JSON output, list commands return a {items, next, has_more} envelope; pass --cursor with a prior page's next to read the following page, or --all to fetch every page. --format ndjson instead streams the items themselves, one JSON object per line. Incomplete pages emit a compact _notice.pagination on stderr with next and has_more; pass that next verbatim as --cursor. Empty filtered pages still carry the notice. Completed pages and --all results do not. --all collects all pages before rendering, including NDJSON.

Multiple servers (contexts)

A single config file can hold several Jira servers as named contexts. Most users need only one and never see the concept — config init --pretty configures a default context and the flow is unchanged. To work with more than one server, re-run config init --pretty and pick Add a new context, then:

jira-cli config get-contexts          # list contexts, current marked
jira-cli config use-context prod      # switch the current context
jira-cli --use-context prod issue get PROJ-123   # override for one command

JIRA_CONTEXT overrides the current context via the environment. Legacy single-server config files are read unchanged.

Errors and exit codes

Failures are JSON on stderr (stdout stays a clean data channel) and map to stable exit codes: 0 success, 2 usage, 3 config, 4 auth, 5 permission, 6 not found, 7 rate limit, 8 network, 9 server, 10 parse, 11 conflict. Each error carries next_steps naming the command to run next, and retryable to guide safe retries. A write can succeed before a follow-up read fails: WRITE_SUCCEEDED_READ_FAILED preserves the issue key and read-only recovery command with retryable: false. Uncertain write outcomes also require verification before another mutation; a non-zero exit is not proof of failure. See error and write-outcome details.

Use as a Go library

The HTTP client that powers the CLI is published as a standalone Go package, so a GUI or other tool can drive Jira directly — same normalized models, Cloud / Data Center flavor handling and structured errors, without shelling out to the binary.

import (
	"context"
	"net/http"
	"os"

	api "github.com/angelmsger/jira-cli/pkg/apiclient"
	cerr "github.com/angelmsger/jira-cli/pkg/errors"
	"github.com/angelmsger/jira-cli/pkg/transport"
)

// Authentication is a transport.Decorator you supply — it sets the
// Authorization header on every request. PAT uses a Bearer token:
func bearer(token string) transport.Decorator {
	return func(r *http.Request) { r.Header.Set("Authorization", "Bearer "+token) }
}

ctx := context.Background()
client, flavor, err := api.Build(ctx, api.BuildParams{
	BaseURL:       "https://jira.example.com",
	Flavor:        "auto", // "cloud" | "datacenter" | "auto"
	AuthDecorator: bearer(os.Getenv("JIRA_PERSONAL_ACCESS_TOKEN")),
})
if err != nil { /* see error handling below */ }

issue, err := client.GetIssue(ctx, api.GetIssueOpts{Key: "PROJ-123"})

Errors are *errors.CLIError with a stable Category and Code, so callers branch on failure kinds instead of parsing strings:

if ce := cerr.AsCLIError(err); ce != nil {
    // ce.Category, ce.Code, ce.Hint, ce.NextSteps, ce.HTTPStatus, ce.Retryable
}

These pkg/... packages primarily back this CLI and its companion Skill; their exported surface is treated as a stable contract. Read the package doc comment (go doc ./pkg/apiclient) before changing it.

Development

make test       # unit + integration tests
make e2e        # build + run against an in-repo mock Jira server
make e2e-live   # additionally run read-only checks against the real server
make lint       # gofmt + go vet
make docs       # regenerate the CLI reference under docs/cli/

The docs/cli/ reference is generated from the cobra command tree by cmd/gen-docs, so it always matches --help. After changing a command or flag, run make docs and commit the result — CI fails if it drifts.

See docs/technical-design.md for the architecture and internal/ package layout, docs/releasing.md for the release process, and CHANGELOG.md for the version history.

Related

Part of a family of agent-facing CLIs — one skeleton, one set of conventions, all built for coding agents. Browse the full set at github.com/AngelMsger:

• jira-cli — Jira issues & workflow transitions (this project)
• confluence-cli — Confluence as a knowledge base
• bitbucket-cli — Bitbucket pull requests & code review
• openobserve-cli — OpenObserve logs, metrics & traces
• jenkins-cli — inspect Jenkins jobs & builds
• prometheus-cli — Prometheus queries, targets, rules & alerts
• wecom-calendar-cli — WeCom calendars, synced locally & annotated

License

Released under the MIT License.

Team setup

An installer can run jira-cli config set-context team --base-url <url> --auth-scheme pat --activate without credentials or network access. Members then run jira-cli auth guide and jira-cli auth login. See team distribution and personal login for environment-only presets, conflict handling, and version-specific credential pages.

To point a prepared team context at a login this machine already has for the same service, whichever scheme it uses (a personal access token, or a password or API token), run jira-cli --use-context team auth reuse --dry-run, then omit --dry-run. The result names the account the login signs in as. See existing-login reuse.

Documentation

Overview

Package jiracli is the module root. It exists only to embed packaged assets — the companion `jira` Skill — into the CLI binary, so that `jira-cli skill install` can deploy a version-matched copy regardless of how the binary itself was installed (npm, go install, prebuilt, source).

Index

• Constants
• Variables

Constants

const SkillRoot = "skills/jira"

SkillRoot is the path within SkillFS at which the Skill is rooted.

Variables

var SkillFS embed.FS

SkillFS holds the companion Skill, rooted at "skills/jira".