atl-axi

Agent-ergonomic Jira Cloud CLI, built on the AXI principles: token-efficient TOON output, minimal schemas, definitive empty states, structured errors, idempotent mutations, and next-step hints.

It talks to the Jira REST API directly - no acli, no MCP server - and works with scoped API tokens. The things agents get wrong in Jira are the plumbing: which customfield_* holds story points on this screen, how to move an issue into a sprint, which end of a "blocks" link is which. atl-axi handles that for them.

$ atl-axi issue view PROJ-123
issue:
  key: PROJ-123
  summary: Retry the sync worker
  type: Task
  status: In Progress
  assignee: Ana Author
  priority: Medium
  points: 3
  sprint: Sprint 7 (active; id 578)
  parent: PROJ-100 Sync reliability
  labels: none
  updated: 1h ago
  links[1]{relation,key,status,summary}:
    is blocked by,PROJ-120,Done,Add backoff helper
  comments: 2
---
Retries transient failures with exponential backoff.
---
help[2]:
  - Run `atl-axi issue comments PROJ-123` to read the 2 comments
  - Run `atl-axi issue transition PROJ-123` to list status transitions

Status: early (v0.1.x). Covered by unit and mocked end-to-end tests and checked against a live Jira Cloud site.

Install

Requires Node.js 20+.

npm install -g atl-axi

Prefer the global install over npx -y atl-axi: npx adds start-up time and, inside npm workspaces, npm notice lines on stderr for every call.

One line in CLAUDE.md / AGENTS.md:

Use `atl-axi` for anything in Jira (issues, JQL, sprints, story points, transitions, comments, links).

Optional: atl-axi setup hooks shows your open issues (and the issue named in the current git branch) at agent session start.

Authenticate

Create an Atlassian API token with scopes for Jira:

read:jira-work write:jira-work (plus read:jira-user for --assignee <name> and your display name, and read:board-scope:jira-software read:sprint:jira-software for sprint list --board)

Scope	For
read:jira-work	everything that reads
write:jira-work	edit, transition, comment, create, link
read:jira-user	optional - --assignee <name>, your display name
read:board-scope:jira-software read:sprint:jira-software	optional - sprint list --board (empty future sprints)

pbpaste | atl-axi auth login --site acme.atlassian.net --email [email protected] --token-stdin
atl-axi auth status   # shows which scope families the token has

• The token is read only from stdin - never from argv, so it cannot land in shell history or an agent transcript - validated against the API, then stored in the OS keychain (macOS Keychain, Windows Credential Manager, libsecret). atl-axi never prompts.
• Use the Atlassian account email.
• Profiles for several accounts or sites: auth login --profile <name> stores one token per profile (default profile: default) with its site, and makes it active. Pick one with -p/--profile <name> after any command, ATL_AXI_PROFILE for a single command, or atl-axi auth use <name>; auth logout --profile <name> removes one. A login from before profiles keeps working as default.
• Requests always go through api.atlassian.com/ex/jira/<cloudId> (required for scoped tokens); the cloud id is looked up from the site.

Environment variables

Override the stored login (CI, containers, agent shells); -p on the command line wins over them:

Variable	Purpose
ATLASSIAN_EMAIL	Atlassian account email (with ATLASSIAN_API_TOKEN)
ATLASSIAN_API_TOKEN	API token (with ATLASSIAN_EMAIL)
ATLASSIAN_SITE	Site, e.g. acme.atlassian.net; the cloud id is looked up and cached
JIRA_CLOUD_ID	Cloud id directly; skips the lookup and wins over ATLASSIAN_SITE
ATL_AXI_NO_KEYCHAIN	1 never reads or writes the OS keychain
ATL_AXI_PROFILE	Profile for a single command (default: the active one)
ATL_AXI_CONFIG_DIR	Config and cache directory (default $XDG_CONFIG_HOME/atl-axi or ~/.config/atl-axi)
ATL_AXI_POINTS_FIELD	Story points field to write (name or id), e.g. customfield_10014, when the issue screen offers a different one

Commands

Command	What it does
atl-axi	Your open issues, plus the issue named in the current git branch
issue view <KEY>	Summary, points, open sprint (with id), parent, links with direction, description. --full, --fields '<name>,...'
issue comments <KEY>	Newest comments as text. --limit, --full
issue edit <KEY>	--points, --sprint <id>, --parent, --assignee me, --labels/--add-label/--remove-label, --priority, --summary, --description, --set '<any field name>=<value>'. Sends only changes; (no-op) when nothing differs
issue transition <KEY> [<target>]	Lists transitions, or moves by transition or status name. --resolution
issue comment <KEY>	--body / --body-file -; plain text becomes ADF. Skips an identical recent comment
issue create	--project --type --summary plus the edit fields. Skips a same-summary issue created in the last day
issue link <A> <relation> <B> / unlink	atl-axi issue link PROJ-1 blocks PROJ-2, 'is blocked by', 'relates to'... Read back after creation
search ["<JQL>"]	--mine, --project, --status, --sprint <id|open>, --text, --fields points,sprint,...
sprint list --project <KEY>	Active/future sprints with ids, from the project's issues (no Agile scopes needed); --board <id> uses the Agile API
sprint issues <id>	Issues in a sprint with a points total and status breakdown
field list	Field ids and types. --search, --custom
project list	Visible projects
api [METHOD] /rest/...	Escape hatch; DELETE needs --confirm

Every command has --help.

Output is strict TOON apart from free text (descriptions, comments) between --- fences. For scripts, --json anywhere on the line prints the same payload as JSON, with free text as fields (description; thread rows for issue comments); errors keep their exit code:

atl-axi search --mine --json | jq -r '.issues[]?.key'

Development

pnpm install
pnpm run check   # typecheck + tests + build + SKILL.md freshness

Other AXI tools

• bb-axi: Bitbucket Cloud CLI for agents
• hetzner-axi: Hetzner Cloud CLI for agents
• mongo-axi: Read-only MongoDB CLI for agents, plus mongo-rw-axi (write-capable MongoDB CLI for agents, loopback hosts only)
• mysql-axi: Read-only MySQL CLI for agents, plus mysql-rw-axi (write-capable MySQL CLI for agents, loopback hosts only)
• secrets-axi: Secrets guard CLI for agents
• ts-axi: TypeScript symbol CLI for agents

License

MIT