@mu-cabin/jira-cli

Agent-first CLI for operating a Jira Server / Data Center instance over its REST API — a generic passthrough over every endpoint the server exposes.

• Targets: any Jira Server / Data Center 7.13.x instance — point it at yours with --base-url / JIRA_API_BASE / config init (the built-in default is a jira.example.com placeholder)
• API: /rest/api/2/ (Jira Server has no /rest/api/3/)
• Auth: HTTP Basic (username + password / PAT) — the account is always supplied by the user, never defaulted

The bundled action index (331 operations, 55 resource categories) was derived from a 7.13.18 instance's WADL — see How the spec is built. Sign in with your own account; point it at a different instance with --base-url if needed.

Install / build

pnpm install
pnpm --filter @mu-cabin/jira-cli build      # or: pnpm build:jira

Quick start

# Sign in — prompts for your username (visible) then password/PAT (hidden),
# saves both, and verifies. Run it in your own terminal. That's the whole setup.
jira login

# Point the CLI at your instance (the built-in default is only a placeholder):
jira config init --base-url https://jira.example.com

# Non-interactive (CI): username via flag, password via stdin
printf %s 'secret' | jira login --username alice --password-stdin

# Re-check anytime
jira whoami

Config lives in ~/.jira/config.json; the password in ~/.jira/credentials.json (mode 0600). Everything can be overridden by env: JIRA_API_BASE, JIRA_USER, JIRA_PASSWORD, JIRA_PROFILE.

Discover

jira categories                       # resources: issue, project, user, ...
jira actions -s issue -m GET          # search by keyword / HTTP method
jira actions -c project               # filter by category
jira schema getIssue                  # method, path, params, body example, risk

Call (generic passthrough)

# path param + query params + response projection
jira call getIssue -p issueIdOrKey=PROJ-123 \
  --select 'fields.summary,fields.status.name'

# list with truncation
jira call getAllProjects --select '[].key' --limit 10

# write with a JSON body (inline, @file, or - for stdin)
jira call createIssue -d '{"fields":{...}}'
jira call editIssue -p issueIdOrKey=PROJ-1 -d @patch.json

# preview without sending (credentials redacted; never gated)
jira call deleteIssue -p issueIdOrKey=PROJ-1 --dry-run

# destructive ops require explicit confirmation (exit 10 otherwise)
jira call deleteIssue -p issueIdOrKey=PROJ-1 --yes

-p Key=Value is routed by the index: matching {placeholders} fill the path, the rest become query params. --select dotpaths are relative to the response body ([] maps over arrays, [n] indexes).

Endpoints not in the index

The index tracks the public 7.13 surface; a given instance may have more. Hit any endpoint directly:

jira call any --method GET --path '/rest/api/2/project/{key}/role' -p key=PROJ

Conventions

• --json emits a single machine-readable envelope: { ok, action, warnings?, data | error }.
• Exit codes: 0 ok · 2 usage · 3 auth · 4 not-found · 5 remote · 8 forbidden · 9 rate-limit · 10 confirm-required · 11 validation. Server HTTP statuses map onto these.
• Risk is classified by HTTP method: GET/HEAD = read, POST/PUT = write, DELETE = destructive (gated behind --yes).

How the spec is built

The pipeline mirrors the source of truth — the live server WADL:

application.wadl  ──wadl-to-openapi──▶  spec/jira-server-7.13-openapi.json
                                          │
                                          └─build-spec──▶  generated/index.json

pnpm build:openapi    # WADL → OpenAPI 3.0.1 (scripts/wadl-to-openapi.ts)
pnpm build:spec       # OpenAPI → action index (scripts/build-spec.ts)
pnpm regen            # both + bundle

# refresh from a running instance instead of the cached WADL:
jira update                       # fetch live WADL, re-derive spec + index
jira update --offline             # rebuild index from the cached spec
jira update --dry-run             # report counts without writing

Files

| Path | Description | |------|-------------| | jira-server-7.13.18.wadl.xml, xsd*.xsd | Source WADL + grammar pulled from the instance | | spec/jira-server-7.13-openapi.json | OpenAPI 3.0.1 derived from the WADL | | generated/index.json | Bundled action index the CLI reads at runtime | | src/core/wadl.ts, src/core/xml.ts | WADL → OpenAPI converter (dependency-free) |

Note: the base URL has a built-in default (the bundled instance) but is fully overridable (--base-url / JIRA_API_BASE / config init); the account is never defaulted — each user signs in with their own. The bundled spec/ and generated/ were derived from a specific 7.13.18 instance and carry its hostname as provenance metadata; regenerate against your own instance with jira update if you'd rather not ship it.