Jira/cli

Jira CLI

jira-cli-tools-generic.md

Jira CLI Tools — Install & Configure

Portable guide — no organization, site, or project specifics. Substitute the placeholders below for your own environment. For the site-specific version used here, see jira-cli-tools.md.

Two different tools both get called "the Jira CLI". They do different jobs and coexist without conflict — different binary names, different config files.

Tool	Binary	Origin	Best for
acli	acli	Atlassian official	Create/edit/transition work items, official API surface, Rovo Dev
jira-cli	jira	ankitpokhrel/jira-cli (community)	Fast JQL triage, issue lists, terminal-friendly views

Both are interactive tools. For automation, prefer the REST API directly — these CLIs have no Atlassian Document Format (ADF) support and their human-readable output is not stable enough to parse reliably.

Placeholders used below

Substitute your own values:

Placeholder	Meaning	Example
YOUR-SITE.atlassian.net	Your Jira Cloud site	acme.atlassian.net
YOUR_EMAIL	Atlassian account email	you@example.com
YOUR_TOKEN	Atlassian API token	ATATT3x...
PROJ	Default project key	ENG
Your Board Name	Default board within that project	ENG Kanban

Create an API token at https://id.atlassian.com/manage-profile/security/api-tokens.

Prerequisites

• Auth: Basic authentication — email + API token, not your password.
• API version: Jira Cloud REST API v3. v2 is deprecated and can return misleading Issue does not exist or you do not have permission to see it. errors that have nothing to do with permissions.
• Jira and Confluence are separate sites even within one organization. The same API token usually works for both, but authenticating one does not authenticate the other.

Verify credentials before blaming a CLI:

curl -s -o /dev/null -w '%{http_code}\n' \
  -u "YOUR_EMAIL:YOUR_TOKEN" \
  https://YOUR-SITE.atlassian.net/rest/api/3/myself
# expect: 200

A 401 means the token or email is wrong; a 404 on a known-good issue usually means you hit v2 instead of v3.

Install (Linux / WSL, x86_64)

Both ship as single static binaries. No root, no package manager.

mkdir -p ~/.local/bin

# --- acli (Atlassian official) ---
curl -fsSL -o ~/.local/bin/acli \
  https://acli.atlassian.com/linux/latest/acli_linux_amd64/acli
chmod +x ~/.local/bin/acli

# --- jira-cli (community) ---
ASSET=$(curl -s https://api.github.com/repos/ankitpokhrel/jira-cli/releases/latest \
  | grep browser_download_url | grep -i 'linux_x86_64.tar.gz' | cut -d'"' -f4)
curl -fsSL -o /tmp/jira.tgz "$ASSET"
tar -xzf /tmp/jira.tgz -C /tmp
mv /tmp/jira_*_linux_x86_64/bin/jira ~/.local/bin/jira
chmod +x ~/.local/bin/jira
rm -rf /tmp/jira.tgz /tmp/jira_*_linux_x86_64

Ensure ~/.local/bin is on PATH:

case ":$PATH:" in
  *":$HOME/.local/bin:"*) echo "already on PATH" ;;
  *) echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc ;;
esac

Confirm:

acli --version
jira version

Other platforms

• macOS (Homebrew):

  brew install ankitpokhrel/jira-cli/jira-cli
  brew tap atlassian/homebrew-acli && brew install acli

  For a manual acli install, swap the URL path to acli_darwin_amd64 or acli_darwin_arm64.

• Windows: download acli_windows_amd64/acli.exe from the same host, and the jira-cli windows_x86_64.zip release asset. Put both anywhere on PATH.
• Linux arm64: substitute acli_linux_arm64 and the jira-cli linux_arm64 asset.

Configure

acli — the token must arrive on stdin

--token is a boolean flag meaning "read the token from standard input". It does not take a value. Passing the token as an argument silently consumes the next argv entry and the login fails in a confusing way.

# Correct — token piped in
printf '%s' "YOUR_TOKEN" | acli jira auth login \
  --site YOUR-SITE.atlassian.net \
  --email "YOUR_EMAIL" \
  --token

# Wrong — do not do this
# acli jira auth login --site ... --email ... --token "YOUR_TOKEN"

Reading from a file works the same way:

acli jira auth login --site YOUR-SITE.atlassian.net --email "YOUR_EMAIL" --token < token.txt

Browser-based OAuth is also available if you'd rather not manage a token:

acli jira auth login --web

Verify:

acli jira auth status   # expect: ✓ Authenticated

jira-cli — needs a board, and reads the token from the environment

jira init is interactive by default. --project alone is not sufficient: it still prompts for a board, so under </dev/null it dies with Unable to generate configuration: EOF. Pass --board explicitly for a fully non-interactive setup.

export JIRA_API_TOKEN="YOUR_TOKEN"   # jira-cli reads this exact variable name

jira init --installation cloud \
  --server "https://YOUR-SITE.atlassian.net" \
  --login "YOUR_EMAIL" \
  --auth-type basic \
  --project PROJ \
  --board "Your Board Name" \
  --force

If you don't know the board name, run jira init interactively once — it lists the boards available in the project and lets you filter by typing.

Notes:

• Config is written to ~/.config/.jira/.config.yml; override the location with JIRA_CONFIG_FILE.
• Re-run with --force to change project or board later.
• JIRA_API_TOKEN must be exported in any shell that runs jira — the token is deliberately not stored in the config file. Put it in your shell profile or a secrets helper.
• For Jira Server/Data Center rather than Cloud, use --installation local, and --auth-type bearer (personal access token) or mtls as appropriate.

Usage

# --- acli ---
acli jira workitem search --jql "project = PROJ AND status = 'To Do' ORDER BY created DESC" --limit 10
acli jira workitem view PROJ-123
acli jira auth status

# --- jira-cli ---
jira issue list -p PROJ --plain --no-headers --columns KEY,STATUS,SUMMARY
jira issue list -p PROJ -a "YOUR_EMAIL" -s "In Progress"
jira issue list -p PROJ --order-by created --reverse
jira issue view PROJ-123
jira open PROJ-123        # opens in browser

--plain --no-headers makes jira-cli output usable in a pipeline, but see the parsing caveat above before depending on it in scripts.

Gotchas

• jira-cli's -q takes a JQL fragment, not a complete query. It is appended to the project/board clause jira-cli builds itself, so an embedded ORDER BY is a syntax error:

  Error in the JQL Query: Expecting ',' but got 'ORDER'. (line 1, character 38)

  Use --order-by <field> and --reverse instead. By contrast, acli --jql does accept a complete query including ORDER BY.

• acli --token reads stdin. This is the single most common acli setup failure — see above.
• jira init hangs or exits with EOF when --board is omitted, even if --project is supplied.
• Jira and Confluence are separate sites. One token, two authentications.
• Corporate TLS interception: if a proxy injects a self-signed certificate, jira-cli accepts jira init --insecure to skip verification. Prefer installing the corporate CA certificate into the system trust store where you can — --insecure disables verification entirely.
• Rate limiting: Atlassian Cloud throttles aggressively. Batch queries with a sensible --limit rather than looping per-issue.