jira

Jira CLI

Bridge natural language to a Jira CLI. Portable across users, projects, instances, and auth models — never hardcode project keys, usernames, servers, tenant hostnames, or board IDs.

A user may have more than one Jira instance configured on their machine (e.g. an on-prem/Server/DC instance alongside a separate Cloud tenant), each requiring a different tool and reachable through a different local alias or shell function. Work phases in order for each request. Skip only phases marked optional when their precondition is unmet.

Phase 0 — Pick the right CLI / instance (multi-instance setups only)

Skip this phase entirely if only one Jira CLI is configured — go straight to Prerequisites below.

If more than one is configured:

1. Detect what's available — check for both tools before assuming: command -v jira, command -v acli, and any wrapper shell functions/aliases the user has defined for each instance. List candidates rather than guessing a name: alias | grep -i jira and declare -f | grep -i jira (or type -a per candidate name) to surface anything ending in or containing jira (e.g. a *jira naming pattern like ckjira/workjira). If that turns up more than one, ask the user which maps to which instance rather than assuming from the name alone. Do not hardcode specific alias names in the skill — they are user-chosen and machine-specific.
2. Match the request to an instance — use whatever the user's project/team/board convention already implies (explicit project key prefix, current repo, or a stated instance name). If ambiguous and more than one instance plausibly applies, ask once rather than guessing which instance a write should land on.
3. Auth model determines the tool, not preference — this is a hard technical constraint, not a style choice:
   • An instance that accepts classic API-token basic or bearer auth → use jira (jira-cli). Config typically lives at a path set by JIRA_CONFIG_FILE or ~/.config/.jira/*.yml; a multi-instance setup may keep one config file per instance and select between them via that env var or a wrapper function.
   • An instance whose Jira Cloud tenant enforces OAuth (classic token Basic/Bearer auth returns 401/403 regardless of token freshness — this is an org-wide Atlassian security policy on that tenant, not an expired-token problem) → jira-cli's --auth-type basic|bearer|mtls cannot authenticate at all; use acli instead, which has a native OAuth 2.0 login flow. See references/acli-jira.md.
   • If unsure which category an instance falls into, jira me (or the equivalent auth-status check for the wrapper in use) failing with a 401/403 on a freshly verified token, or an error mentioning OAuth/Connect Session Auth, is the signal to switch tools rather than keep retrying token regeneration.
4. Never mix command grammars — jira-cli and acli have different flag shapes for the same intent (positional issue key vs. --key, different flag names). Once you've picked a tool for this request, use only that tool's syntax for the rest of the exchange. jira-cli syntax is documented inline below and in references/{examples,jql,formatting,transitions}.md; acli syntax is documented in references/acli-jira.md.