Jira AI CLI

An AI-friendly CLI for Jira that prioritizes efficiency and security.

Core Benefits

1. Context Efficiency: Eliminates redundant context data, consuming significantly fewer tokens than Jira MCP or similar tools.
2. Bullet-proof Security: Restrict AI to only the actions you permit, ensuring your environment remains secure.

Start

• AI Agent: Project overview and commands

Installation

npm install -g jira-ai

Quick Start

Authenticate with credentials (non-interactive — JSON or .env file only):

jira-ai auth --from-json '{"url":"https://your-domain.atlassian.net","email":"[email protected]","apikey":"your-api-token"}'

See all available commands:

jira-ai --help

JSON Output

All commands always output structured JSON. Use global flags to control formatting:

• Default: pretty-printed JSON (2-space indentation)
• --compact: single-line JSON for maximum token efficiency

jira-ai issue get PROJ-123
jira-ai --compact project list
jira-ai --compact issue search "project = PROJ AND status = Open"

Errors are returned as structured JSON to stdout:

{ "error": true, "message": "Issue not found", "hints": ["Check the issue key"], "exitCode": 1 }

Issue Hierarchy Tree

Explore issue hierarchies with the issue tree command. It returns a directed graph (nodes + edges) representing the full parent-child hierarchy starting from a given issue:

jira-ai issue tree PROJ-10

Include linked issues as leaf nodes:

jira-ai issue tree PROJ-10 --links

Filter linked issues by type and limit depth:

jira-ai issue tree PROJ-10 --links --types "Blocks,Relates" --depth 2 --max-nodes 100

Sprint Hierarchy Tree

View all issues in a sprint organized by their hierarchy (epics → stories → subtasks):

jira-ai sprint tree 42

Customize traversal depth and node limit:

jira-ai sprint tree 42 --depth 4 --max-nodes 500

Rich Issue Management

Create issues with detailed field support:

jira-ai issue create --title "New feature" --project PROJ --issue-type Task \
  --priority High --description "Feature details" --labels "feature,backend" \
  --component "api" --fix-version "v2.0" --due-date 2026-04-15 --assignee "John Doe"

Update issues with any combination of fields:

jira-ai issue update PROJ-123 --priority Critical --summary "Updated title" \
  --labels "urgent" --due-date 2026-05-01

Discover available fields for a project (including custom fields):

jira-ai project fields PROJ --type Task

Transition Issues

Change the status of an issue:

jira-ai issue transition PROJ-123 "In Progress"

Add a comment and resolution during transition:

jira-ai issue transition PROJ-123 Done --resolution Done --comment "Completed the feature."

Change assignee and fix version during transition:

jira-ai issue transition PROJ-123 "In Review" --assignee "Jane Smith" --fix-version "v2.0"

Set a custom field during transition:

jira-ai issue transition PROJ-123 Done --custom-field "Story Points=5"

Pass a comment from a file (useful for long comments):

jira-ai issue transition PROJ-123 Done --comment-file ./release-notes.md

Discover which transitions are available and what fields they require:

jira-ai issue transitions PROJ-123

Only show transitions that have required fields:

jira-ai issue transitions PROJ-123 --required-only

Get structured output for scripting:

jira-ai issue transitions PROJ-123

When a transition fails due to missing required fields, the error message lists what is needed and suggests running issue transitions <key> to discover them.

Service Account Authentication

Atlassian service accounts use scoped API tokens that must authenticate through the api.atlassian.com gateway rather than direct site URLs.

Using a .env file

Create a .env file with your service account credentials:

JIRA_HOST=your-domain.atlassian.net
[email protected]
JIRA_API_TOKEN=your-service-account-api-token
JIRA_AUTH_TYPE=service_account

Then authenticate:

jira-ai auth --from-file path/to/.env

The Cloud ID will be auto-discovered from your site URL. To provide it explicitly:

JIRA_CLOUD_ID=your-cloud-id

Using CLI flags

jira-ai auth --service-account --from-json '{"url":"...","email":"...","apikey":"..."}'

Or with an explicit Cloud ID:

jira-ai auth --service-account --cloud-id your-cloud-id --from-json '{"url":"...","email":"...","apikey":"..."}'

How it works

Standard Jira API tokens authenticate directly against your-domain.atlassian.net. Service account tokens are scoped and must route through the Atlassian API gateway at api.atlassian.com/ex/jira/{cloudId}/....

When authType is set to service_account, jira-ai automatically:

1. Discovers your Cloud ID from https://your-domain.atlassian.net/_edge/tenant_info (if not provided)
2. Routes all API requests through https://api.atlassian.com/ex/jira/{cloudId} instead of the direct site URL
3. Uses the same basic auth (email + API token) — just through the gateway

Existing configurations using standard API tokens are unaffected.

Saved Queries

Define reusable JQL queries in your settings.yaml under the saved-queries key to avoid repeating common searches.

Configuration

Add a saved-queries map to your settings.yaml — each key is a query name (lowercase alphanumeric with hyphens) and each value is a JQL string:

saved-queries:
  my-open-bugs: "project = PROJ AND status = Open AND issuetype = Bug"
  overdue-tasks: "project = PROJ AND duedate < now() AND status != Done"
  my-assignee: "assignee = currentUser()"

Usage

Run a saved query by name:

jira-ai issue search --query my-open-bugs

List all configured saved queries:

jira-ai issue search --list-queries

Combine with result limits:

jira-ai issue search --query overdue-tasks --limit 10

Saved queries are mutually exclusive with raw JQL — you cannot provide both a positional JQL argument and --query at the same time.

Configuration & Restrictions

Tool allows you to have very complex configutations of what Projects/Jira commands/Issue types you would have acess to thought the tool. Use this command to start setup:

jira-ai settings --help

All avalible commands: https://github.com/festoinc/jira-ai/blob/main/all_avaliable_commands.md

Links

• Repository: https://github.com/festoinc/jira-ai
• Issues: https://github.com/festoinc/jira-ai/issues
• NPM: https://www.npmjs.com/package/jira-ai

License

Apache License 2.0