jira-cli

Non-interactive CLI for Jira Cloud and Jira Server/Data Center. JSON by default, markdown on request, designed to be driven by an agent. Cloud uses REST v3 + ADF; Server/Data Center uses REST v2 + wiki/plain text bodies.

Prerequisite: the jira binary must be installed (npm install -g @888aaen/jira-cli) and authenticated. If jira ping fails, see references/auth-setup.md.

Boot sequence

1. jira auth status - is a token present in the keychain?
2. If missing -> the user logs in themselves; point them to references/auth-setup.md. Never handle the token yourself.
3. jira ping - verifies token + connectivity against the API.
4. jira config show - inspect the active profile and defaults.
5. Pick a command from the index below.

Draft before writing (human approval required)

Never run a mutating command without showing the user the exact command and its effect, then getting their approval. Covers issue create, edit, delete, assign, move, comment add, link / unlink, clone, and sprint add / start / close.

Flow: draft -> approve -> execute.

1. Draft. Show the exact command line(s) and a one-line summary of the effect.
2. Approve. Wait for confirmation. If they want changes, redraft and show it again — never execute a partially-approved change.
3. Execute. Run the approved command verbatim. If a key won't resolve or a field is rejected, stop and re-draft — don't improvise a different write.

Reads (list, view, search, attachment downloads, me/mine, ping, board/project/user queries) never mutate Jira — run them freely, including to gather data for an accurate draft. Attachment downloads do write to the explicit local --output path.

Core rules

1. Draft mutating commands for approval before running them. See Draft before writing. Reads run freely.
2. JSON is the default output. Parse it directly. Use --format markdown only when rendering for the user.
3. Never invent keys. Resolve project keys via jira project list, issue keys via jira issue list / jira search, account IDs via jira user search.
4. JQL values use double quotes: status = "In Progress", project = "PROJ".
5. Set and activate a named context once to stop repeating flags: jira context set work --project PROJ --board-id 42 --profile default && jira context use work.
6. --profile NAME overrides the active context's authentication profile for a single command.
7. jira auth status is local-only (keychain check). Use jira ping or jira auth whoami to confirm the token actually works.
8. Custom fields use raw IDs: --field customfield_10016=5. Repeatable.
9. Bodies are Markdown. --body/-b (and comment text) take CommonMark - headings, lists, fenced code blocks, links, bold/italic. The CLI converts it to ADF on Cloud and wiki markup on Server/DC. Write Markdown, not raw {code}/h3. wiki syntax.
10. Respect the boundary. jira boundary show lists what you may access (projects and required labels). Every command is confined to it, and requests outside it fail with outside the jira boundary. You may change the context freely, but changing the boundary requires sudo, which only the user can do. Never run sudo jira boundary … yourself, and never try to bypass the boundary (editing boundary files, changing permissions, reusing cached sudo credentials, or calling Jira outside this CLI). If you need wider access, show the user the exact command, e.g. sudo jira boundary set --project PROJ --label safe, and ask them to run it. jira api is refused while a boundary is active.

Intent -> command

When no predefined command fits, use jira api: it sends a raw request with the profile's auth and prints the response verbatim. Full paths (starting with /) pass through unchanged; shorthand paths like issue/PROJ-1 get the platform prefix for the instance flavor (/rest/api/3 on Cloud, /rest/api/2 on Server/Data Center). -d implies POST (@file and - for stdin work); find the right endpoint first with jira api --list <terms>, which searches an embedded catalog of the official API for the profile's flavor. Errors print Jira's error body and exit non-zero.

For anything not listed, run jira <group> --help - help is authoritative. Failed commands automatically include the failing command's full help text on stderr; use it to correct the next call instead of repeating the same command.

jira issue get PROJ-123 returns attachment metadata in fields.attachment by default and adds a structured nextSteps download command when attachments exist. In markdown, that command appears at the bottom under Next steps. Prefer an attachment ID when downloading because filenames can be duplicated. Download to an explicit local path, then inspect that path with the available image, document, archive, or text-reading tool. The same guidance is available through jira issue get --help and jira issue attachment download --help:

jira issue get PROJ-123 | jq '.fields.attachment[] | {id, filename, mimeType, size}'
jira issue attachment download PROJ-123 10042 --output /tmp/jira-10042.png

Never fetch the content URL with unauthenticated curl or expose credentials to another host; let the CLI perform the authenticated download. Binary bytes are never printed to stdout.

Dependency commands inherit the active project/context filters and accept explicit scope flags; --status "Define,To Do,Backlog" selects multiple statuses. jira issue ready orders actionable issues by how many unresolved issues they directly unblock. jira issue graph retains linked blockers outside the selected scope as inScope: false; inspect .cycles before trying to sequence cyclic work. Use jira issue graph-pretty when a human should verify the full topology: it builds the graph first, layers it by dependency depth, and draws continuous top-down branch and join lines. ●, ○, ✓, ◇, and ↻ mark ready, blocked, resolved, external, and cyclic nodes. A blocker counts as resolved only when Jira's resolution field is set. Both "blocks" and "depends on" link types are followed by default; use --link-type NAME (repeatable) to follow only specific link types.

Example graph-pretty output:

Dependency graph (blocker ──▶ blocked)
Legend: ● ready  ○ blocked  ✓ resolved  ◇ external  ↻ cycle

Component 1
          ● PROJ-1
              │
       ┌──────┴──────┐
       ▼             ▼
   ○ PROJ-2      ○ PROJ-3
       │             │
       └──────┬──────┘
              ▼
          ○ PROJ-4

Output format

Persistent default: jira context set NAME --display markdown. The --format flag always wins.

When to load a reference file

• Auth not working, first-time setup, multiple Jira instances, CI/automation tokens -> references/auth-setup.md
• Writing JQL beyond trivial queries -> references/jql-cookbook.md
• End-to-end issue lifecycle examples -> references/workflows.md

Reporting CLI problems

If the jira CLI itself misbehaves (a crash, a wrong result, a missing flag — not a Jira data error), and gh is installed (gh --version succeeds) and authenticated, offer to file a bug. Get the user's OK first, then:

gh issue create --repo AndersSpringborg/jira-agent-cli \
  --title "<short summary>" \
  --body "<exact command run, expected vs actual, jira --version, OS>"

If gh is missing or not authenticated, give the user the title and body to file manually at https://github.com/AndersSpringborg/jira-agent-cli/issues. Never paste tokens or secrets into an issue.