Jira CLI for agents — designed with AXI (Agent eXperience Interface).

Wraps the official Atlassian CLI (acli) with token-efficient TOON output, definitive totals, contextual next-step suggestions, and structured error handling. Built for autonomous agents that interact with Jira via shell execution.

Measured gains

Jira's REST payloads are built for rendering UIs: avatar URLs in four sizes, self links on every entity, status categories with color names. acli --json passes them through verbatim; an agent reads about six scalars per work item. acli-axi flattens each item to those scalars and emits TOON.

Measured on a live Jira Cloud site (same query and filters both sides, single run, 2026-07-13):

| Command | acli --json | acli-axi | Reduction | | ------------------- | ----------- | -------- | ---------- | | search (25 items) | 71,947 ch | 4,983 ch | −93.1% | | search (5 items) | 15,181 ch | 744 ch | −95.1% | | view (1 item) | 3,619 ch | 841 ch | −76.8% | | sprints | 653 ch | 240 ch | −63.2% |

Latency is parity (mean +18 ms on a ~1.2–1.8 s Jira round-trip). The gain scales with result count — per-item overhead is what gets flattened — and compounds in agent sessions, where tool output is re-read as input on every subsequent turn.

Quick Start

Install the acli-axi skill in the Agent Skills format with npx skills:

npx skills add mathieu-neron/acli-axi --skill acli-axi -g

The skill teaches your agent when to reach for acli-axi and how to install the CLI (npm install -g acli-axi, with npx -y acli-axi for one-off runs). You still need acli installed and authenticated via acli jira auth login --web (Node 20+ required).

The skill is not a user-facing slash command (user-invocable: false). Just ask for anything that touches Jira — searching or triaging work items with JQL, filing stories or bugs, editing summaries or assignees, or checking a board's sprints — and the agent loads the skill on its own when it recognizes the task.

-g installs the skill for all projects (~/.claude/skills/, for example); drop it to install for the current project only (.claude/skills/).

Other Ways to Install

The skill is the recommended path, but it is not the only one.

Global install

npm install -g acli-axi

Upgrade later with the built-in acli-axi update (or acli-axi update --check to only look).

Zero setup

acli-axi is an AXI, so any capable agent can run the CLI directly with nothing installed at all. Just tell your agent:

Execute `npx -y acli-axi` to get Jira tools.

From source

Clone and pack a tarball:

git clone https://github.com/mathieu-neron/acli-axi.git
cd acli-axi && npm pack && npm install -g ./acli-axi-*.tgz

Do not npm install -g the git URL directly — on npm 10/11 a global git install can be reified as a symlink into npm's temporary clone, which npm deletes after install, leaving a broken binary that still reported success. Tarball installs copy files and cannot hit this. Verify any install with acli-axi --version.

Usage

acli-axi                            # home - auth state + your open work items, no args needed
acli-axi search --jql "project = TEAM AND sprint in openSprints()"
acli-axi search --jql "..." --limit 50 --fields key,summary,labels
acli-axi view TEAM-123              # long descriptions truncated; --full to expand
acli-axi sprints --board 36         # active + future sprints by default
acli-axi create --project TEAM --type Story --summary "New thing" --assignee @me
acli-axi create --project TEAM --type Story --summary "..." \
  --parent TEAM-93 -f customfield_10028=1 -f customfield_10020=11144  # custom fields (points, sprint)
acli-axi edit TEAM-123 --summary "Better title"   # never prompts (--yes under the hood)

List output reports the true total, not the page size: when a search fills its --limit, acli-axi runs acli's --count behind the scenes and tells you total: 14724, showing: 25 with a hint to raise the limit.

Custom fields (-f/--field <id>=<value>, repeatable) are create-only: acli's edit schema rejects them, and acli-axi says so with a structured error instead of failing cryptically. Values that parse as JSON become numbers or arrays; everything else stays a string.

Commands

| Command | Description | | --------- | --------------------------------------------------------------------- | | search | Search work items with JQL — flattened rows, definitive totals | | view | Full detail for one work item — ADF descriptions as plain text | | create | Create a work item — flags plus -f custom fields, echoes invariants | | edit | Edit a work item — summary, assignee, labels, type; never prompts | | sprints | List a board's sprints — active + future by default | | update | Built-in self-update command inherited from axi-sdk-js |

Global flags

• --help — show help for any command
• -v, -V, --version — show the installed acli-axi version

Errors are structured (error: + code: + help:): exit 2 for usage errors, exit 1 for everything else; stdout is data, stderr is diagnostics.

Scope

v0.1 covers Jira core, plus the installable Agent Skill above. Not wrapped yet (use acli directly): comments, transitions, attachments, links, projects, filters, Confluence. Also deferred: session hooks (installSessionStartHooks in the SDK).

Development

pnpm install
pnpm run build       # Compile TypeScript to dist/
pnpm run build:skill # Regenerate skills/acli-axi/SKILL.md from the CLI's own help
pnpm test            # Run tests with vitest (the acli boundary is mocked)

The committed skills/acli-axi/SKILL.md is generated by pnpm run build:skill; pnpm test fails if it drifts from the generator — never hand-edit it. The npm package includes skills/acli-axi/, so published releases ship the same installable Agent Skill documented in Quick Start.

Built on axi-sdk-js, which provides command dispatch, TOON serialization, structured errors, and the update command.

License

MIT