# Jira AI > Jira AI CLI - AI Agent Skill - Skill: `festoinc/jira-ai` (Agent Skill, multi-file: 15 files) - Install (CLI): `npx skillmds@latest add festoinc/jira-ai` - Raw SKILL.md: https://api.skillmd.com/api/skills/festoinc/jira-ai/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: festoinc (https://skillmd.com/u/festoinc) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/festoinc/jira-ai --- # 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 ```bash npm install -g jira-ai ``` ### Authentication Provide credentials via JSON string or `.env` file (no interactive prompts): ```bash 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: ```bash jira-ai auth --from-file path/to/.env ``` ### Setup Settings & Restrictions ```bash 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 ` — Validate a settings YAML file (schema + deep validation) without applying it. - `jira-ai settings --apply ` — 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 ```bash 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: ```json { "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. ```bash 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 `: 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 ` to run a saved query, `--list-queries` to list saved queries, `--limit ` to cap results, `--comment-author ` to filter by comment author (display name or account ID; works with both positional JQL and `--query`). - `issue transition `: Change issue status. Supports `--resolution `, `--comment `, `--comment-file `, `--assignee `, `--fix-version `, `--custom-field "Field Name=value"`. Supports `--dry-run` to preview without transitioning. - `issue transitions `: List available transitions for an issue, including required fields. Supports `--required-only`. - `issue update `: 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 `: Add comment from Markdown file. - `issue assign `: Assign issue. - `issue label `: Manage labels. - `issue link types`: List all available issue link types. - `issue link list `: List all links (inward + outward) for an issue. - `issue link create `: Create a link between two issues (e.g., `"Blocks"`, `"Relates"`). - `issue link delete --target `: Delete a link between two issues. - `issue tree `: 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 --file [--file ]...`: Upload one or more files as attachments. Returns attachment metadata (id, filename, size, mimeType, author, created). - `issue attach list `: List all attachments on an issue with metadata (id, filename, size, author, created). - `issue attach download --id [--output ]`: Download an attachment by ID. Saves to the specified path, or defaults to the attachment filename in the current directory. - `issue attach delete --id `: Remove an attachment from an issue. - `issue activity `: Show a unified activity feed (changelog + comments) for an issue. Use `--since ` to filter by time, `--limit ` (default 50) to cap results, `--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 ` to filter by author, and `--compact` to strip comment bodies for efficiency. Returns `{ issueKey, activities, totalChanges, hasMore }`. - `issue comments `: List comments on an issue. Use `--limit ` (default 50) to cap results, `--since ` to filter by time, and `--reverse` for chronological (oldest-first) order (default is newest first). Returns `{ issueKey, comments, total, hasMore }`. - `issue worklog list `: List all worklogs for an issue. Use `--started-after ` and `--started-before ` (UNIX ms) to filter by time range, `--author-account-id ` to filter by author. - `issue worklog add `: Log time against an issue. Requires `--time ` (e.g., `1h`, `30m`, `1d2h30m`, `1w`). Optional: `--comment `, `--started ` (defaults to now, timezone offsets auto-normalized), `--adjust-estimate `, `--new-estimate `, `--reduce-by `. Supports `--dry-run`. - `issue worklog update `: Update an existing worklog. Requires `--id ` and at least one of `--time`, `--comment`, `--started`. Optional: `--adjust-estimate`, `--new-estimate`. Supports `--dry-run`. - `issue worklog delete `: Delete a worklog entry. Requires `--id `. Optional: `--adjust-estimate`, `--new-estimate`, `--increase-by `. Supports `--dry-run`. ### Projects & Users - `project list`: List accessible projects. - `project fields `: Discover available fields including custom fields. Use `--type ` to filter by issue type, `--custom` for custom fields only, `--search ` to search by name. - `user search [project-key]`: Find users. - `user worklog `: Retrieve worklogs for a user over a timeframe (e.g., `7d`, `30d`). Use `--group-by-issue` to group results by issue, `--project ` to restrict to a specific project. - `user activity `: Retrieve a user's activity across all issues (comments, status changes, field changes, links, attachments). Use `--project ` to restrict to a project, `--types ` to filter activity types (comma-separated: `comment_added`, `comment_updated`, `status_change`, `field_change`, `link_added`, `link_removed`, `attachment_added`, `attachment_removed`), `--limit ` 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 `: List epics in a project (`--done` to include completed, `--max ` to limit). - `epic get `: Get full epic details. - `epic create `: Create a new epic (`--name`, `--summary` required; `--description`, `--labels` optional). - `epic update `: Update epic name and/or summary. - `epic issues `: List issues belonging to an epic (`--max ` to limit). - `epic link `: Link an issue to an epic (`--epic `). - `epic unlink `: Remove an issue from its epic. - `epic progress `: Show epic completion progress with visual bar. ### Boards, Sprints & Backlog - `board list [--project ] [--type ]`: List accessible boards. - `board get `: Get board details. - `board config `: Get board configuration (columns, filter, rank field). - `board issues `: List issues on a board (`--jql`, `--max`). - `board rank --issues --before |--after `: Rank issues on a board. - `sprint list [--state ]`: List sprints for a board. - `sprint get `: Get sprint details. - `sprint create --name `: Create a sprint (`--goal`, `--start`, `--end` optional). - `sprint start `: Start a future sprint. - `sprint complete `: Complete an active sprint. - `sprint update `: Update sprint (`--name`, `--goal`, `--start`, `--end`). - `sprint delete `: Delete a sprint. - `sprint issues `: List issues in a sprint (`--jql`, `--max`). - `sprint move --issues `: Move issues to a sprint. - `sprint tree `: 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 `: Move issues to the backlog. ### Saved Queries Define reusable JQL queries in `settings.yaml`: ```yaml saved-queries: my-open-bugs: "project = PROJ AND status = Open AND issuetype = Bug" ``` - `issue search --query `: Run a saved query. - `issue search --list-queries`: List all saved queries. ### Confluence - `confl get `: Retrieve Confluence page content. - `confl create `: Create a new page. - `confl update <url>`: Update page content from Markdown. For a full list of commands, refer to the [Available Commands](https://github.com/festoinc/jira-ai/blob/main/all_avaliable_commands.md) documentation.