jira-cli

README

Jira CLI

A fast, scriptable command-line interface for Jira — Cloud and Server/Data Center — over the REST API. Manage issues, JQL search, transitions, comments, worklogs, attachments, links, boards and sprints from your terminal.

Designed for both human operators and coding agents. All list/get commands support -o json and -o yaml for machine-readable output.

Independent open-source wrapper over the Jira REST API. Not affiliated with Atlassian and unrelated to Atlassian's official acli.

Features

• Every auth method — Cloud API token (default), scoped API token, OAuth 2.0 (3LO) browser login with auto-refresh, Server/DC personal access token, and username/password. See docs/CREDENTIALS.md.
• Issues — JQL search, list, get, create, edit, delete, assign, transition.
• Around issues — comments, worklogs, attachments (upload/download), links, watchers, votes.
• Projects, users, fields and Agile boards / sprints / epics.
• ADF-aware — descriptions and comments are sent as Atlassian Document Format; --markdown supported.
• Agent-friendly — -o json|yaml, --read-only safety mode, --no-input, env-var config, clean stdout/stderr separation, automatic rate-limit (429) backoff.
• Cross-platform — macOS, Linux, Windows (amd64 and arm64). Multiple named profiles.

Installation

Install script (recommended — no Go required)

Installs the latest prebuilt binary for your OS/arch:

curl -sSfL https://raw.githubusercontent.com/piyush-gambhir/jira-cli/main/install.sh | sh

Pin a version or change the install directory:

curl -sSfL https://raw.githubusercontent.com/piyush-gambhir/jira-cli/main/install.sh | VERSION=0.1.1 sh
curl -sSfL https://raw.githubusercontent.com/piyush-gambhir/jira-cli/main/install.sh | INSTALL_DIR=~/.local/bin sh

Download a release manually

Prebuilt binaries for every platform are attached to each GitHub Release. Download the archive for your OS/arch, extract, and put jira on your PATH:

# example (macOS arm64) — adjust the version/asset name
curl -sSfL https://github.com/piyush-gambhir/jira-cli/releases/latest/download/jira-cli_darwin_arm64.tar.gz | tar xz
sudo mv jira /usr/local/bin/

Assets are named jira-cli_<os>_<arch>.tar.gz (lowercase), where <os> is darwin or linux and <arch> is amd64 or arm64 (Windows ships as jira-cli_windows_amd64.zip).

Alternative (build from source, requires Go)

Requires the Go 1.22+ toolchain.

go install github.com/piyush-gambhir/jira-cli@latest

Or clone and build:

git clone https://github.com/piyush-gambhir/jira-cli.git
cd jira-cli
make install          # builds and installs to $GOBIN / $GOPATH/bin

The binary is jira.

Quick start

# 1. Authenticate — browser OAuth by default (released binaries have the app built in)
jira auth login
#    prefer an API token (no app needed)? — prompts for site, email, token
jira auth login --type api_token
#    or non-interactively / in CI (uses API token under the hood):
export JIRA_SITE=https://acme.atlassian.net JIRA_EMAIL=me@acme.com JIRA_TOKEN=xxxx

# 2. Confirm
jira whoami
jira status

# 3. Work
jira issue search "assignee = currentUser() AND statusCategory != Done" -o json
jira issue create -p ABC --type Task --summary "Set up CI" -d "Details here"
jira issue transition ABC-123 "In Progress"
jira issue comment ABC-123 --body "On it"

Authentication methods

--type	Deployment	Credential
oauth2 (default)	Cloud	OAuth 2.0 3LO browser login (refresh tokens; app baked into released binaries)
api_token	Cloud	email + API token (no app needed)
scoped	Cloud	email + scoped token (api.atlassian.com gateway)
pat	Server/DC	bearer personal access token
basic	Server/DC	username + password

jira auth login --type pat --site https://jira.company.com --token "$PAT"
jira auth login --type oauth2 --client-id "$ID" --client-secret "$SECRET" --scope-preset admin
jira auth list   ;   jira auth use staging   ;   jira auth logout --name staging

OAuth scopes are selectable: --scope-preset read|write|admin|all (or an interactive picker), plus granular --scope. See docs/CREDENTIALS.md.

For end users

Everyone authenticates to their own Jira account. Released binaries have an OAuth app baked in, so jira auth login opens the browser and you just click Accept. Prefer a token (or building from source without an app)? Run jira auth login --type api_token and paste one from id.atlassian.com (~30s).

Output

-o table (default), -o json, -o yaml. Informational messages go to stderr; data goes to stdout, so jira ... -o json | jq is always safe.

Documentation

• CLAUDE.md — complete command guide and workflows
• jira/references/commands.md — full command/flag reference
• docs/CREDENTIALS.md — all authentication methods, in depth
• API references: issues, search/JQL/projects/users, agile/ADF/conventions

Releasing (maintainers)

Releases are built by GoReleaser via GitHub Actions on any v* tag — see .github/workflows/release.yml and .goreleaser.yaml.

git tag -s v0.1.0 -m "v0.1.0"     # signed tag
git push origin v0.1.0            # -> CI builds cross-platform binaries + checksums and publishes a Release

To ship a build with a built-in OAuth app (so users can browser-login with no app registration), add repo secrets JIRA_OAUTH_CLIENT_ID / JIRA_OAUTH_CLIENT_SECRET (Settings → Secrets and variables → Actions). They're injected via -ldflags and never stored in source. Locally, the same values live in a gitignored .env, consumed by make build, ./install.sh, and ./scripts/release.sh. Without them, builds ship credential-free (API token / BYO OAuth).

Development

make build     # -> bin/jira
make test      # go test -race ./...
make vet
make fmt       # gofmt -s -w .

Commits and tags are signed and required — the repository enforces a "require signed commits" ruleset on GitHub, and local config (commit.gpgsign, tag.gpgsign) signs by default. See CONTRIBUTING.md.

License

See LICENSE.