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 }

Dry-Run / Preview Mode

Preview write operations without executing them. The --dry-run flag is available on issue create, issue update, issue transition, and issue worklog add/update/delete. No Jira API write calls are made — output is purely a preview.

jira-ai issue update PROJ-123 --priority High --dry-run
jira-ai issue transition PROJ-123 Done --resolution Fixed --dry-run
jira-ai issue create --project PROJ --type Bug --title "Fix crash" --dry-run
jira-ai issue worklog add PROJ-123 --time 2h --comment "Debugging" --dry-run

Dry-run output follows a consistent JSON structure:

{
  "dryRun": true,
  "command": "issue.update",
  "target": "PROJ-123",
  "changes": {
    "priority": { "from": "Medium", "to": "High" }
  },
  "preview": { "...": "same output as the real command" },
  "message": "No changes were made. Remove --dry-run to execute."
}

The preview field contains the same output the real command would produce, so AI agents can process it identically. Phase 1 supports issue create, issue update, and issue transition. Worklog dry-run: issue worklog add, issue worklog update, issue worklog delete.

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.

Activity Feed & Comments

View a unified activity feed combining changelog entries and comments for an issue:

jira-ai issue activity PROJ-123

Filter by time, activity type, or author:

jira-ai issue activity PROJ-123 --since 2026-01-01T00:00:00Z --types status_change,comment_added --author "Jane Smith"

Use --compact to strip comment bodies for maximum token efficiency:

jira-ai issue activity PROJ-123 --compact

List comments on an issue:

jira-ai issue comments PROJ-123

Use --reverse for chronological (oldest-first) order, or --since to filter by time:

jira-ai issue comments PROJ-123 --since 2026-01-01T00:00:00Z --reverse --limit 20

Activity types: status_change, field_change, comment_added, comment_updated, attachment_added, attachment_removed, link_added, link_removed

User Activity

Retrieve a user's activity across all issues in a timeframe — comments, status changes, field changes, and more:

jira-ai user activity "Jane Smith" 7d

Filter by project:

jira-ai user activity "Jane Smith" 7d --project PS

Filter by activity type:

jira-ai user activity "Jane Smith" 7d --types comment_added,status_change

Group results by issue instead of a flat timeline:

jira-ai user activity "Jane Smith" 14d --project PS --group-by-issue

Use --compact to strip comment bodies for token efficiency:

jira-ai --compact user activity "Jane Smith" 30d --types comment_added

Set a result limit:

jira-ai user activity "Jane Smith" 7d --limit 100

Permission: user.activity — must be explicitly granted (not covered by user.worklog).

Worklog Management

Log time against issues with full CRUD support:

jira-ai issue worklog add PROJ-123 --time 2h

Add a comment and specify when the work started:

jira-ai issue worklog add PROJ-123 --time 1d2h30m --comment "Backend refactor" --started "2026-04-15T09:00:00+02:00"

The --started flag accepts any standard ISO 8601 timestamp. Timezone offsets are automatically normalized to Jira's required format (yyyy-MM-dd'T'HH:mm:ss.SSS±HHMM):

• 2026-04-15T07:00:00Z → 2026-04-15T07:00:00.000+0000
• 2026-04-15T10:00:00+03:00 → 2026-04-15T10:00:00.000+0300
• 2026-04-15T07:00:00-05:30 → 2026-04-15T07:00:00.000-0530

When omitted, --started defaults to the current time.

Log time with estimate adjustment (--adjust-estimate accepts auto, new, leave, or manual):

jira-ai issue worklog add PROJ-123 --time 4h --adjust-estimate new --new-estimate 2d

Use --reduce-by with --adjust-estimate manual to decrease the remaining estimate:

jira-ai issue worklog add PROJ-123 --time 3h --adjust-estimate manual --reduce-by 2h

List worklogs for an issue:

jira-ai issue worklog list PROJ-123

Filter by time range or author:

jira-ai issue worklog list PROJ-123 --started-after 1713139200000 --started-before 1715731200000
jira-ai issue worklog list PROJ-123 --author-account-id 557058:abc123-def456-ghi789

Update an existing worklog:

jira-ai issue worklog update PROJ-123 --id 12345 --time 3h --comment "Updated after review"

Delete a worklog (use --increase-by with --adjust-estimate manual to restore estimate):

jira-ai issue worklog delete PROJ-123 --id 12345
jira-ai issue worklog delete PROJ-123 --id 12345 --adjust-estimate manual --increase-by 2h

Preview any write operation with --dry-run:

jira-ai issue worklog add PROJ-123 --time 2h --dry-run

Duration format uses Jira-style notation: 1w (5 working days), 1d (8 hours), 1h, 30m, or combinations like 1d2h30m.

User Worklog

Retrieve worklogs for a specific user over a timeframe:

jira-ai user worklog "Jane Smith" 7d

Group results by issue:

jira-ai user worklog "Jane Smith" 30d --group-by-issue

Restrict to a specific project:

jira-ai user worklog "Jane Smith" 30d --project PS

Issue Search Enhancements

Search issues with JQL and filter by comment author:

jira-ai issue search 'project = PS AND updated >= -7d' --comment-author "Jane Smith"

Use --comment-author without a JQL query to find all issues commented on by a user:

jira-ai issue search --comment-author "Jane Smith" --limit 50

--comment-author can be combined with both positional JQL and --query (saved queries).

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.

Presets

Predefined configuration presets let you quickly set up permission levels without manually editing settings.yaml. Presets configure allowed-commands, allowed-jira-projects, and allowed-confluence-spaces in one step.

The --preset, --list-presets, --detect-preset, --apply, --validate, and --reset flags are mutually exclusive — only one can be used at a time.

Available Presets

| Preset | Description | | :--- | :--- | | read-only | AI can only observe. No create, update, delete, or transition operations. | | standard | AI can perform common productive actions but cannot do destructive operations (delete, sprint management). | | my-tasks | AI has full command access but is restricted to issues where the current user participated (assignee, reporter, commenter, or watcher). | | yolo | Unrestricted access. The AI can do everything. The name explicitly signals risk. |

What each preset allows

• read-only — issue get/search/stats/comments/activity/tree/worklog.list/link.list/link.types/attach/list, project list/statuses/types/fields, user me/search/worklog/activity, confl get/spaces/pages/search, epic list/get/issues/progress, board list/get/config/issues, sprint list/get/issues/tree
• standard — Everything in read-only, plus issue create/update/transition/comment/assign/label.add/label.remove/link.create/attach.upload/attach.download/worklog.add/worklog.update, confl create/comment/update, epic create/update/link/unlink, sprint update
• my-tasks — All commands across all domains (issue, project, user, confl, epic, board, sprint, backlog), but issue visibility is filtered to those where the user participated (see globalParticipationFilter below)
• yolo — All commands, all projects, all Confluence spaces. No restrictions.

Usage

Apply a preset:

jira-ai settings --preset read-only
jira-ai settings --preset standard
jira-ai settings --preset my-tasks
jira-ai settings --preset yolo

List all available presets with their full configuration details:

jira-ai settings --list-presets

Detect which preset (if any) your current settings match:

jira-ai settings --detect-preset

If your settings don't match any preset exactly, --detect-preset reports custom and shows the closest match with a diff of added/removed commands.

Reset settings to defaults:

jira-ai settings --reset

Validate a settings file without applying it:

jira-ai settings --validate my-settings.yaml

Apply a settings file:

jira-ai settings --apply my-settings.yaml

View current settings:

jira-ai settings

After applying a preset, you can further customize permissions by editing ~/.jira-ai/settings.yaml. Saved queries are preserved when switching presets.

globalParticipationFilter

The my-tasks preset sets a globalParticipationFilter in settings.yaml that restricts which issues the AI can see and interact with. Only issues where the current user matches at least one participation criterion are accessible:

defaults:
  globalParticipationFilter:
    was_assignee: true
    was_reporter: true
    was_commenter: true
    is_watcher: true

| Field | JQL equivalent | Meaning | | :--- | :--- | :--- | | was_assignee | assignee was currentUser() | User was ever assigned to the issue | | was_reporter | reporter = currentUser() | User is the issue reporter | | was_commenter | issue in issueHistory() | User commented on the issue | | is_watcher | issue in watchedIssues() | User is watching the issue |

The filter applies to both search queries (JQL is automatically wrapped) and direct issue access (per-issue validation). You can customize the filter after applying a preset by editing ~/.jira-ai/settings.yaml — set individual fields to false to relax that criterion.

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.

Quick setup with presets

The fastest way to configure permissions is with a preset (see Presets above):

jira-ai settings --preset standard

Manual setup

Use this command to start setup:

jira-ai settings --help

You can also validate or apply settings from a YAML file:

jira-ai settings --validate my-settings.yaml
jira-ai settings --apply my-settings.yaml

To revert to default settings:

jira-ai settings --reset

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