Jira AI CLI - AI Agent Skill
An AI-friendly CLI for Jira designed for maximum efficiency and security. All output is structured JSON — no human-readable formatting, no interactive prompts.
Why Use Jira AI CLI?
- Efficiency: Consumes significantly fewer tokens than Jira MCP or similar tools by eliminating redundant context data.
- Security: Bullet-proof security by restricting AI actions to only what you permit.
Installation & Setup
npm install -g jira-ai
Authentication
Provide credentials via JSON string or .env file (no interactive prompts):
jira-ai auth --from-json '{"url":"https://your-domain.atlassian.net","email":"you@example.com","apikey":"your-api-token"}'
Or use a .env file for service accounts:
jira-ai auth --from-file path/to/.env
Setup Settings & Restrictions
jira-ai settings --help
Presets
Apply predefined permission presets instead of manually configuring settings:
jira-ai settings --preset read-only — AI can only observe; no create, update, delete, or transition operations. Includes user.activity for read-only user activity monitoring.jira-ai settings --preset standard — AI can perform common productive actions but not destructive operations. Includes user.activity for team management.jira-ai settings --preset my-tasks — Full command access but restricted to issues where the current user participated (assignee, reporter, commenter, or watcher). Sets a globalParticipationFilter that gates both searches and direct issue access.jira-ai settings --preset yolo — Unrestricted access. The name explicitly signals risk.jira-ai settings --list-presets — List all presets with their full configuration details.jira-ai settings --detect-preset — Detect which preset matches your current settings. Reports custom with closest-match diff if no exact match.jira-ai settings --reset — Revert settings to defaults.jira-ai settings --validate <file> — Validate a settings YAML file (schema + deep validation) without applying it.jira-ai settings --apply <file> — Validate and apply settings from a YAML file.jira-ai settings — View current settings.
All settings flags are mutually exclusive. After applying a preset, customize further by editing ~/.jira-ai/settings.yaml. Saved queries are preserved.
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 issue get PROJ-123
jira-ai project list
jira-ai 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. Add --dry-run to issue create, issue update, issue transition, or issue worklog add/update/delete to see exactly what would change — no Jira API write calls are made.
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 --dry-run
Output includes dryRun: true, the command, target, changes (before/after values), a preview (same format as the real command), and a message confirming no changes were made.
Phase 1 scope: issue create, issue update, issue transition. Worklog dry-run: issue worklog add, issue worklog update, issue worklog delete.
Command Overview
Issues
issue get <issue-id>: Retrieve issue details. Response includes an attachments array with id, filename, size, author, and created timestamp.issue create: Create a new issue. Supports --title, --project, --issue-type, --parent (for subtasks), --priority, --description, --description-file, --labels, --component, --fix-version, --due-date, --assignee, --custom-field. Supports --dry-run to preview without creating.issue search [jql]: Execute JQL search. Use --query <name> to run a saved query, --list-queries to list saved queries, --limit <n> to cap results, --comment-author <name> to filter by comment author (display name or account ID; works with both positional JQL and --query).issue transition <issue-id> <status>: Change issue status. Supports --resolution <name>, --comment <text>, --comment-file <path>, --assignee <email-or-name>, --fix-version <name>, --custom-field "Field Name=value". Supports --dry-run to preview without transitioning.issue transitions <issue-id>: List available transitions for an issue, including required fields. Supports --required-only.issue update <issue-id>: Update one or more fields of an issue. Supports --priority, --summary, --description, --from-file, --labels, --clear-labels, --component, --fix-version, --due-date, --assignee, --custom-field. Supports --dry-run to preview without updating.issue comment <issue-id>: Add comment from Markdown file.issue assign <issue-id> <account-id>: Assign issue.issue label <add|remove> <issue-id> <labels>: Manage labels.issue link types: List all available issue link types.issue link list <issue-key>: List all links (inward + outward) for an issue.issue link create <source-key> <link-type> <target-key>: Create a link between two issues (e.g., "Blocks", "Relates").issue link delete <source-key> --target <target-key>: Delete a link between two issues.issue tree <issue-key>: Show the full issue hierarchy tree rooted at an issue (epic → story → subtasks). Use --links to include linked issues as leaf nodes, --depth N (default 3) to limit traversal depth, --max-nodes N (default 200) to cap nodes, --types TYPES to filter link types. Returns { root, nodes, edges, depth, truncated, totalNodes }.issue attach upload <issue-key> --file <path> [--file <path>]...: Upload one or more files as attachments. Returns attachment metadata (id, filename, size, mimeType, author, created).issue attach list <issue-key>: List all attachments on an issue with metadata (id, filename, size, author, created).issue attach download <issue-key> --id <attachment-id> [--output <path>]: Download an attachment by ID. Saves to the specified path, or defaults to the attachment filename in the current directory.issue attach delete <issue-key> --id <attachment-id>: Remove an attachment from an issue.issue activity <issue-key>: Show a unified activity feed (changelog + comments) for an issue. Use --since <ISO-timestamp> to filter by time, --limit <n> (default 50) to cap results, --types <types> (comma-separated: status_change, field_change, comment_added, comment_updated, attachment_added, attachment_removed, link_added, link_removed) to filter by activity type, --author <name-or-email> to filter by author, and --compact to strip comment bodies for efficiency. Returns { issueKey, activities, totalChanges, hasMore }.issue comments <issue-key>: List comments on an issue. Use --limit <n> (default 50) to cap results, --since <ISO-timestamp> to filter by time, and --reverse for chronological (oldest-first) order (default is newest first). Returns { issueKey, comments, total, hasMore }.issue worklog list <issue-id>: List all worklogs for an issue. Use --started-after <timestamp> and --started-before <timestamp> (UNIX ms) to filter by time range, --author-account-id <accountId> to filter by author.issue worklog add <issue-id>: Log time against an issue. Requires --time <duration> (e.g., 1h, 30m, 1d2h30m, 1w). Optional: --comment <text>, --started <ISO-datetime> (defaults to now, timezone offsets auto-normalized), --adjust-estimate <auto|new|leave|manual>, --new-estimate <duration>, --reduce-by <duration>. Supports --dry-run.issue worklog update <issue-id>: Update an existing worklog. Requires --id <worklog-id> and at least one of --time, --comment, --started. Optional: --adjust-estimate, --new-estimate. Supports --dry-run.issue worklog delete <issue-id>: Delete a worklog entry. Requires --id <worklog-id>. Optional: --adjust-estimate, --new-estimate, --increase-by <duration>. Supports --dry-run.
Projects & Users
project list: List accessible projects.project fields <project-key>: Discover available fields including custom fields. Use --type <issue-type> to filter by issue type, --custom for custom fields only, --search <term> to search by name.user search [project-key]: Find users.user worklog <user> <timeframe>: Retrieve worklogs for a user over a timeframe (e.g., 7d, 30d). Use --group-by-issue to group results by issue, --project <key> to restrict to a specific project.user activity <user> <timeframe>: Retrieve a user's activity across all issues (comments, status changes, field changes, links, attachments). Use --project <key> to restrict to a project, --types <types> to filter activity types (comma-separated: comment_added, comment_updated, status_change, field_change, link_added, link_removed, attachment_added, attachment_removed), --limit <n> to cap results, --group-by-issue to group by issue instead of timeline, and --compact to strip comment bodies. Returns { user, timeframe, project, activities, total, hasMore, issueCount } in timeline mode or { issues, ... } in group-by-issue mode. Requires user.activity permission.
Epics
epic list <project-key>: List epics in a project (--done to include completed, --max <n> to limit).epic get <epic-key>: Get full epic details.epic create <project-key>: Create a new epic (--name, --summary required; --description, --labels optional).epic update <epic-key>: Update epic name and/or summary.epic issues <epic-key>: List issues belonging to an epic (--max <n> to limit).epic link <issue-key>: Link an issue to an epic (--epic <epic-key>).epic unlink <issue-key>: Remove an issue from its epic.epic progress <epic-key>: Show epic completion progress with visual bar.
Boards, Sprints & Backlog
board list [--project <key>] [--type <type>]: List accessible boards.board get <board-id>: Get board details.board config <board-id>: Get board configuration (columns, filter, rank field).board issues <board-id>: List issues on a board (--jql, --max).board rank --issues <keys> --before <key>|--after <key>: Rank issues on a board.sprint list <board-id> [--state <state>]: List sprints for a board.sprint get <sprint-id>: Get sprint details.sprint create <board-id> --name <name>: Create a sprint (--goal, --start, --end optional).sprint start <sprint-id>: Start a future sprint.sprint complete <sprint-id>: Complete an active sprint.sprint update <sprint-id>: Update sprint (--name, --goal, --start, --end).sprint delete <sprint-id>: Delete a sprint.sprint issues <sprint-id>: List issues in a sprint (--jql, --max).sprint move <sprint-id> --issues <keys>: Move issues to a sprint.sprint tree <sprint-id>: Show all issues in a sprint organized by hierarchy (epics → stories → subtasks). Use --depth N (default 3) and --max-nodes N (default 200). Returns { root, nodes, edges, depth, truncated, totalNodes } with a virtual sprint root node.backlog move --issues <keys>: Move issues to the backlog.
Saved Queries
Define reusable JQL queries in settings.yaml:
saved-queries:
my-open-bugs: "project = PROJ AND status = Open AND issuetype = Bug"
issue search --query <name>: Run a saved query.issue search --list-queries: List all saved queries.
Confluence
confl get <url>: Retrieve Confluence page content.confl create <space> <title>: Create a new page.confl update <url>: Update page content from Markdown.
For a full list of commands, refer to the Available Commands documentation.
1---2name: jira-ai3description: Jira AI CLI - AI Agent Skill4---5# Jira AI CLI - AI Agent Skill67An AI-friendly CLI for Jira designed for maximum efficiency and security. All output is structured JSON — no human-readable formatting, no interactive prompts.89## Why Use Jira AI CLI?10- **Efficiency:** Consumes significantly fewer tokens than Jira MCP or similar tools by eliminating redundant context data.11- **Security:** Bullet-proof security by restricting AI actions to only what you permit.1213## Installation & Setup1415```bash16npm install -g jira-ai17```1819### Authentication20Provide credentials via JSON string or `.env` file (no interactive prompts):2122```bash23jira-ai auth --from-json '{"url":"https://your-domain.atlassian.net","email":"you@example.com","apikey":"your-api-token"}'24```2526Or use a `.env` file for service accounts:27```bash28jira-ai auth --from-file path/to/.env29```3031### Setup Settings & Restrictions32```bash33jira-ai settings --help34```3536### Presets3738Apply predefined permission presets instead of manually configuring settings:3940- `jira-ai settings --preset read-only` — AI can only observe; no create, update, delete, or transition operations. Includes `user.activity` for read-only user activity monitoring.41- `jira-ai settings --preset standard` — AI can perform common productive actions but not destructive operations. Includes `user.activity` for team management.42- `jira-ai settings --preset my-tasks` — Full command access but restricted to issues where the current user participated (assignee, reporter, commenter, or watcher). Sets a `globalParticipationFilter` that gates both searches and direct issue access.43- `jira-ai settings --preset yolo` — Unrestricted access. The name explicitly signals risk.44- `jira-ai settings --list-presets` — List all presets with their full configuration details.45- `jira-ai settings --detect-preset` — Detect which preset matches your current settings. Reports `custom` with closest-match diff if no exact match.46- `jira-ai settings --reset` — Revert settings to defaults.47- `jira-ai settings --validate <file>` — Validate a settings YAML file (schema + deep validation) without applying it.48- `jira-ai settings --apply <file>` — Validate and apply settings from a YAML file.49- `jira-ai settings` — View current settings.5051All settings flags are mutually exclusive. After applying a preset, customize further by editing `~/.jira-ai/settings.yaml`. Saved queries are preserved.5253## JSON Output5455All commands always output structured JSON. Use global flags to control formatting:5657- Default: pretty-printed JSON (2-space indentation)58- `--compact`: single-line JSON for maximum token efficiency5960```bash61jira-ai issue get PROJ-12362jira-ai --compact issue get PROJ-12363jira-ai project list64jira-ai issue search "project = PROJ AND status = Open"65```6667Errors are returned as structured JSON to stdout:68```json69{ "error": true, "message": "Issue not found", "hints": ["Check the issue key"], "exitCode": 1 }70```7172## Dry-Run / Preview Mode7374Preview write operations without executing them. Add `--dry-run` to `issue create`, `issue update`, `issue transition`, or `issue worklog add/update/delete` to see exactly what would change — no Jira API write calls are made.7576```bash77jira-ai issue update PROJ-123 --priority High --dry-run78jira-ai issue transition PROJ-123 Done --resolution Fixed --dry-run79jira-ai issue create --project PROJ --type Bug --title "Fix crash" --dry-run80jira-ai issue worklog add PROJ-123 --time 2h --dry-run81```8283Output includes `dryRun: true`, the `command`, `target`, `changes` (before/after values), a `preview` (same format as the real command), and a `message` confirming no changes were made.8485Phase 1 scope: `issue create`, `issue update`, `issue transition`. Worklog dry-run: `issue worklog add`, `issue worklog update`, `issue worklog delete`.8687## Command Overview8889### Issues90- `issue get <issue-id>`: Retrieve issue details. Response includes an `attachments` array with id, filename, size, author, and created timestamp.91- `issue create`: Create a new issue. Supports `--title`, `--project`, `--issue-type`, `--parent` (for subtasks), `--priority`, `--description`, `--description-file`, `--labels`, `--component`, `--fix-version`, `--due-date`, `--assignee`, `--custom-field`. Supports `--dry-run` to preview without creating.92- `issue search [jql]`: Execute JQL search. Use `--query <name>` to run a saved query, `--list-queries` to list saved queries, `--limit <n>` to cap results, `--comment-author <name>` to filter by comment author (display name or account ID; works with both positional JQL and `--query`).93- `issue transition <issue-id> <status>`: Change issue status. Supports `--resolution <name>`, `--comment <text>`, `--comment-file <path>`, `--assignee <email-or-name>`, `--fix-version <name>`, `--custom-field "Field Name=value"`. Supports `--dry-run` to preview without transitioning.94- `issue transitions <issue-id>`: List available transitions for an issue, including required fields. Supports `--required-only`.95- `issue update <issue-id>`: Update one or more fields of an issue. Supports `--priority`, `--summary`, `--description`, `--from-file`, `--labels`, `--clear-labels`, `--component`, `--fix-version`, `--due-date`, `--assignee`, `--custom-field`. Supports `--dry-run` to preview without updating.96- `issue comment <issue-id>`: Add comment from Markdown file.97- `issue assign <issue-id> <account-id>`: Assign issue.98- `issue label <add|remove> <issue-id> <labels>`: Manage labels.99- `issue link types`: List all available issue link types.100- `issue link list <issue-key>`: List all links (inward + outward) for an issue.101- `issue link create <source-key> <link-type> <target-key>`: Create a link between two issues (e.g., `"Blocks"`, `"Relates"`).102- `issue link delete <source-key> --target <target-key>`: Delete a link between two issues.103- `issue tree <issue-key>`: Show the full issue hierarchy tree rooted at an issue (epic → story → subtasks). Use `--links` to include linked issues as leaf nodes, `--depth N` (default 3) to limit traversal depth, `--max-nodes N` (default 200) to cap nodes, `--types TYPES` to filter link types. Returns `{ root, nodes, edges, depth, truncated, totalNodes }`.104- `issue attach upload <issue-key> --file <path> [--file <path>]...`: Upload one or more files as attachments. Returns attachment metadata (id, filename, size, mimeType, author, created).105- `issue attach list <issue-key>`: List all attachments on an issue with metadata (id, filename, size, author, created).106- `issue attach download <issue-key> --id <attachment-id> [--output <path>]`: Download an attachment by ID. Saves to the specified path, or defaults to the attachment filename in the current directory.107- `issue attach delete <issue-key> --id <attachment-id>`: Remove an attachment from an issue.108- `issue activity <issue-key>`: Show a unified activity feed (changelog + comments) for an issue. Use `--since <ISO-timestamp>` to filter by time, `--limit <n>` (default 50) to cap results, `--types <types>` (comma-separated: `status_change`, `field_change`, `comment_added`, `comment_updated`, `attachment_added`, `attachment_removed`, `link_added`, `link_removed`) to filter by activity type, `--author <name-or-email>` to filter by author, and `--compact` to strip comment bodies for efficiency. Returns `{ issueKey, activities, totalChanges, hasMore }`.109- `issue comments <issue-key>`: List comments on an issue. Use `--limit <n>` (default 50) to cap results, `--since <ISO-timestamp>` to filter by time, and `--reverse` for chronological (oldest-first) order (default is newest first). Returns `{ issueKey, comments, total, hasMore }`.110- `issue worklog list <issue-id>`: List all worklogs for an issue. Use `--started-after <timestamp>` and `--started-before <timestamp>` (UNIX ms) to filter by time range, `--author-account-id <accountId>` to filter by author.111- `issue worklog add <issue-id>`: Log time against an issue. Requires `--time <duration>` (e.g., `1h`, `30m`, `1d2h30m`, `1w`). Optional: `--comment <text>`, `--started <ISO-datetime>` (defaults to now, timezone offsets auto-normalized), `--adjust-estimate <auto|new|leave|manual>`, `--new-estimate <duration>`, `--reduce-by <duration>`. Supports `--dry-run`.112- `issue worklog update <issue-id>`: Update an existing worklog. Requires `--id <worklog-id>` and at least one of `--time`, `--comment`, `--started`. Optional: `--adjust-estimate`, `--new-estimate`. Supports `--dry-run`.113- `issue worklog delete <issue-id>`: Delete a worklog entry. Requires `--id <worklog-id>`. Optional: `--adjust-estimate`, `--new-estimate`, `--increase-by <duration>`. Supports `--dry-run`.114115### Projects & Users116- `project list`: List accessible projects.117- `project fields <project-key>`: Discover available fields including custom fields. Use `--type <issue-type>` to filter by issue type, `--custom` for custom fields only, `--search <term>` to search by name.118- `user search [project-key]`: Find users.119- `user worklog <user> <timeframe>`: Retrieve worklogs for a user over a timeframe (e.g., `7d`, `30d`). Use `--group-by-issue` to group results by issue, `--project <key>` to restrict to a specific project.120- `user activity <user> <timeframe>`: Retrieve a user's activity across all issues (comments, status changes, field changes, links, attachments). Use `--project <key>` to restrict to a project, `--types <types>` to filter activity types (comma-separated: `comment_added`, `comment_updated`, `status_change`, `field_change`, `link_added`, `link_removed`, `attachment_added`, `attachment_removed`), `--limit <n>` to cap results, `--group-by-issue` to group by issue instead of timeline, and `--compact` to strip comment bodies. Returns `{ user, timeframe, project, activities, total, hasMore, issueCount }` in timeline mode or `{ issues, ... }` in group-by-issue mode. Requires `user.activity` permission.121122### Epics123- `epic list <project-key>`: List epics in a project (`--done` to include completed, `--max <n>` to limit).124- `epic get <epic-key>`: Get full epic details.125- `epic create <project-key>`: Create a new epic (`--name`, `--summary` required; `--description`, `--labels` optional).126- `epic update <epic-key>`: Update epic name and/or summary.127- `epic issues <epic-key>`: List issues belonging to an epic (`--max <n>` to limit).128- `epic link <issue-key>`: Link an issue to an epic (`--epic <epic-key>`).129- `epic unlink <issue-key>`: Remove an issue from its epic.130- `epic progress <epic-key>`: Show epic completion progress with visual bar.131132### Boards, Sprints & Backlog133- `board list [--project <key>] [--type <type>]`: List accessible boards.134- `board get <board-id>`: Get board details.135- `board config <board-id>`: Get board configuration (columns, filter, rank field).136- `board issues <board-id>`: List issues on a board (`--jql`, `--max`).137- `board rank --issues <keys> --before <key>|--after <key>`: Rank issues on a board.138- `sprint list <board-id> [--state <state>]`: List sprints for a board.139- `sprint get <sprint-id>`: Get sprint details.140- `sprint create <board-id> --name <name>`: Create a sprint (`--goal`, `--start`, `--end` optional).141- `sprint start <sprint-id>`: Start a future sprint.142- `sprint complete <sprint-id>`: Complete an active sprint.143- `sprint update <sprint-id>`: Update sprint (`--name`, `--goal`, `--start`, `--end`).144- `sprint delete <sprint-id>`: Delete a sprint.145- `sprint issues <sprint-id>`: List issues in a sprint (`--jql`, `--max`).146- `sprint move <sprint-id> --issues <keys>`: Move issues to a sprint.147- `sprint tree <sprint-id>`: Show all issues in a sprint organized by hierarchy (epics → stories → subtasks). Use `--depth N` (default 3) and `--max-nodes N` (default 200). Returns `{ root, nodes, edges, depth, truncated, totalNodes }` with a virtual sprint root node.148- `backlog move --issues <keys>`: Move issues to the backlog.149150### Saved Queries151152Define reusable JQL queries in `settings.yaml`:153154```yaml155saved-queries:156 my-open-bugs: "project = PROJ AND status = Open AND issuetype = Bug"157```158159- `issue search --query <name>`: Run a saved query.160- `issue search --list-queries`: List all saved queries.161162### Confluence163- `confl get <url>`: Retrieve Confluence page content.164- `confl create <space> <title>`: Create a new page.165- `confl update <url>`: Update page content from Markdown.166167For a full list of commands, refer to the [Available Commands](https://github.com/festoinc/jira-ai/blob/main/all_avaliable_commands.md) documentation.
festoinc