back
loading skill details...
Jira issue management skill for OpenClaw using the jirac CLI. Requires the `jirac` binary to be installed and authenticated before use. Use when listing, vie...
---
name: jirac
description: Jira issue management skill for OpenClaw using the jirac CLI. Requires the `jirac` binary to be installed and authenticated before use. Use when listing, viewing, creating, updating, transitioning, commenting on, attaching files to, bulk-editing, cloning, deleting, linking, archiving, moving, changing types of Jira issues, logging work, generating standup or sprint summaries, managing sprint lifecycles, browsing fix versions, scanning Jira mention notifications, rendering markdown to ADF, registering jirac-mcp into MCP clients, or running raw Jira REST calls from agent workflows.
metadata: {"openclaw":{"emoji":"🎫","requires":{"bins":["jirac"]},"install":[{"id":"github-releases","kind":"download","label":"Install jirac from GitHub Releases","url":"https://github.com/mulhamna/jira-commands/releases","extract":false}],"homepage":"https://github.com/mulhamna/jira-commands"}}
---
Use `jirac` as the Jira execution surface. The CLI is a single Rust binary that supports Jira Cloud and Jira Data Center, multi-profile auth, runtime custom-field discovery, attachment upload, sprint lifecycle, and an interactive TUI with full mouse support.
## Requirements
- Require the `jirac` binary from the official `jira-commands` release source.
- Require Jira authentication to be configured before use, typically via `jirac auth login` in the target environment.
- Treat Jira credentials, local config (`~/.config/jira/config.toml`), and attachment file paths as sensitive.
- For MCP-based agent setups, additionally require the `jirac-mcp` binary (separate package).
## Pre-flight
1. Run `jirac --version` to confirm the binary is installed.
2. Run `jirac auth status` to confirm credentials are configured and reachable. If not, prompt the user to run `jirac auth login` (or `jirac auth login --profile NAME` for separate accounts).
3. For multi-profile setups, run `jirac auth profiles` and `jirac auth use <name>` to switch the active profile before issuing operations.
## Workflow
1. Prefer direct `jirac` commands over raw Jira REST API (`jirac api`) calls when the CLI already supports the action.
2. Use `jirac issue fields -p PROJ --issue-type Type` when required fields, allowed values, or custom fields are unclear.
3. Use `jirac issue transition <KEY>` without a transition argument to get an interactive picker when the target status is unknown.
4. Use `jirac issue standup` for a concise personal update from assigned work, and `jirac issue sprint-summary -p PROJ` for a project sprint rollup.
5. Use `jirac issue sprints -p PROJ` to see sprint lifecycle states before creating, starting, completing, updating, or deleting a sprint.
6. Use `jirac issue notifications` to scan Jira @mentions from issue descriptions and comments.
7. Use `jirac issue render --input file.md` to preview how Markdown will convert to Jira ADF before sending it as description or comment.
8. Use `jirac tui -p PROJ` for any interactive bulk browse / triage / quick-edit workflow — supports mouse (click rows, tabs, picker options; scroll wheel; drag splitter; click `[?]` / `[🔔]`).
9. Confirm intent before destructive or high-impact operations: `delete`, `archive`, `bulk-update`, `bulk-transition`, `bulk-comment`, `bulk-create`, `change-type`, `move`, `sprint-delete`, and attachment uploads.
10. Keep Jira project keys, issue keys, status names, and transition names exact. Use quotes for any name with spaces.
## Common commands
```bash
# Auth and profiles
jirac auth login # interactive, current shell profile
jirac auth login --profile work-cloud # named profile
jirac auth status
jirac auth profiles
jirac auth use work-cloud
# List, search, summaries
jirac issue list # your assigned issues
jirac issue list -p PROJ
jirac issue list --jql 'project = PROJ AND status = "In Progress"'
jirac issue standup # daily standup rollup
jirac issue sprint-summary -p PROJ # current sprint
jirac issue sprint-summary -p PROJ --sprint 'Sprint 24'
jirac issue notifications # @mentions scan
jirac issue view PROJ-123
jirac issue view PROJ-123 --versions # include fix-version block
jirac issue fields -p PROJ --issue-type Bug
jirac issue jql --run # interactive JQL builder
# Sprint lifecycle
jirac issue sprints -p PROJ
jirac issue sprint-create -p PROJ --name 'Sprint 25' --goal 'Ship auth v2'
jirac issue sprint-start <SPRINT_ID>
jirac issue sprint-complete <SPRINT_ID>
jirac issue sprint-update <SPRINT_ID> --name 'Sprint 25 (extended)' --goal 'New goal'
jirac issue sprint-delete <SPRINT_ID> --force # destructive
# Versions
jirac issue versions -p PROJ # browse + backlog preview
jirac issue versions -p PROJ --version 'v1.2.0'
# Create
jirac issue create -p PROJ # interactive
jirac issue create -p PROJ -t Bug -s 'login crash' --assignee me
jirac issue create -p PROJ -t Story -s 'auth flow' --sprint 'Sprint 24' --field story_points=5
jirac issue create -p PROJ -t Sub-task -s 'sub-task' --parent PROJ-100
# Update
jirac issue update PROJ-123 --summary 'New title'
jirac issue update PROJ-123 --priority High --assignee me
jirac issue update PROJ-123 --labels backend,api --fix-versions v2.0
jirac issue update PROJ-123 --field story_points=8
# Transition (positional, not --to)
jirac issue transition PROJ-123 # interactive picker
jirac issue transition PROJ-123 'Done'
jirac issue transition PROJ-123 'In Progress'
# Comment / bulk-comment
jirac issue comment list PROJ-123
jirac issue comment add PROJ-123 --body 'QA verified in staging'
jirac issue bulk-comment --jql 'project = PROJ AND sprint = openSprints()' --body 'Standup reminder'
jirac issue bulk-comment --keys PROJ-1,PROJ-2,PROJ-3 --body 'Please update'
# Worklog
jirac issue worklog list PROJ-123
jirac issue worklog add PROJ-123 --time '2h' --comment 'Implementation work'
jirac issue worklog delete PROJ-123 <WORKLOG_ID>
# Attach
jirac issue attach PROJ-123 ./screenshot.png
# Links between issues
jirac issue link list-types
jirac issue link add --link-type Blocks PROJ-123 PROJ-456 # PROJ-123 blocks PROJ-456
jirac issue link add --link-type Relates PROJ-123 PROJ-456
jirac issue link delete <LINK_ID>
# Clone, change-type, move, delete, archive
jirac issue clone PROJ-123 # same project
jirac issue clone PROJ-123 --project NEWPROJ --summary 'Copy: original'
jirac issue change-type PROJ-123 Bug # native Jira move semantics
jirac issue move PROJ-123 NEWPROJ # cross-project, native (not clone+delete)
jirac issue delete PROJ-123 # prompts confirmation
jirac issue delete PROJ-123 --force
jirac issue archive --jql 'project = PROJ AND resolution = Done AND updated < -180d'
# Bulk operations
jirac issue bulk-transition --jql 'project = PROJ AND status = "To Do"' --to 'In Progress'
jirac issue bulk-update --jql 'project = PROJ AND assignee = EMPTY' --assignee me
jirac issue bulk-update --jql 'project = PROJ AND priority = Low' --priority High --force
jirac issue bulk-create --manifest issues.json
# Batch (mixed ops from manifest)
jirac issue batch --manifest ops.json
# Render markdown → Jira ADF preview
jirac issue render --input description.md
# Raw REST passthrough (last resort)
jirac api GET /rest/api/3/myself
jirac api POST /rest/api/3/issue --body '{"fields":{...}}'
# TUI
jirac tui # uses default project or assigned issues
jirac tui -p PROJ
# MCP server registration (optional)
jirac mcp doctor # check prereqs
jirac mcp install # interactive client picker
jirac mcp install --client claude-code
jirac mcp install --client cursor
```
## Bulk-create manifest format
```json
[
{
"project": "PROJ",
"summary": "Issue title",
"type": "Task",
"assignee": "user@org.com",
"priority": "High",
"labels": ["backend"],
"parent": "PROJ-100",
"description": "Markdown description",
"fields": { "customfield_10016": 5 }
}
]
```
## Batch manifest format
```json
[
{ "op": "create", "project": "PROJ", "summary": "New task", "type": "Task" },
{ "op": "update", "key": "PROJ-10", "priority": "High", "assignee": "me" },
{ "op": "transition", "key": "PROJ-11", "to": "Done" },
{ "op": "archive", "key": "PROJ-12" }
]
```
## JQL quoting
JQL strings often contain spaces, parentheses, and quotes — wrap the entire `--jql` value in single quotes in bash, then use double quotes inside:
```bash
jirac issue list --jql 'project = PROJ AND status = "In Progress" AND assignee = currentUser()'
```
For Windows PowerShell, the inverse — wrap in double quotes outside, escape inner doubles with `` ` ``:
```powershell
jirac issue list --jql "project = PROJ AND status = `"In Progress`""
```
See `references/jql.md` for common JQL recipes.
## Guidance
- Prefer interactive or metadata-assisted flows when field requirements are unclear (`jirac issue fields ...`, `jirac issue jql --run`, `jirac issue transition KEY`).
- Always confirm intent before operations that may change workflow state, bulk-edit, delete, archive, change type, or move issues across projects.
- Confirm that local files selected for attachment are intended and safe to upload.
- Prefer explicit project scoping (`-p PROJ`) when working across multiple Jira projects.
- `jirac issue transition` takes a positional transition name/ID — not `--to`.
- `jirac issue change-type` and `jirac issue move` use Jira's native move semantics; the issue key is preserved.
- For agents that need Jira inside an MCP client (Claude Code, Cursor, Codex, OpenCode, Gemini CLI, Zed), install `jirac-mcp` separately, then run `jirac mcp install` for an interactive registration picker.
## References
- Install guide: `references/install.md`
- JQL recipes: `references/jql.md`
don't have the plugin yet? install it then click "run inline in claude" again.
added comprehensive decision points for multi-profile auth, field discovery, destructive operations, error handling, and edge cases (empty result sets, timeouts, malformed manifests); expanded inputs to document oauth scopes, credential storage, and optional MCP binary; broke original monolithic workflow into 25 granular numbered steps with explicit inputs and outputs; structured output contract by operation type with file locations and data formats; documented outcome signals so user knows skill worked (issue key returned, status changed, comment visible, etc.); preserved original intent, commands, manifest formats, and jql quoting guidance verbatim.
use jirac to manage Jira issues across list, view, create, update, transition, comment, attach, bulk-edit, clone, delete, link, archive, move, type-change, worklog, sprint lifecycle, fix version browse, notification scan, markdown render, and raw REST operations. run this skill when you need to manipulate Jira issues from the command line with multi-profile auth support, custom-field discovery, attachment upload, and optional MCP integration. the binary supports both Jira Cloud and Data Center.
jirac binary:
jira authentication:
jirac auth login to be run in target environment before any issue operations.~/.config/jira/config.toml (treat as sensitive).jirac auth login --profile NAME.external connection:
JIRAC_PROFILE (optional, overrides active profile at runtime).optional MCP integration:
jirac-mcp binary (separate package) for Claude Code, Cursor, or other MCP clients.jirac mcp install after downloading jirac-mcp.file inputs (for operations):
--manifest issues.json) or batch ops (--manifest ops.json).jirac issue render --input file.md).pre-flight check: run jirac --version to confirm binary is installed and accessible. then run jirac auth status to verify credentials are configured and Jira is reachable. if auth fails, prompt user to run jirac auth login or jirac auth login --profile NAME for named profiles.
select profile (multi-profile setups): if working across multiple Jira instances, run jirac auth profiles to list available profiles, then jirac auth use <name> to switch the active profile before any subsequent operations.
discover required fields (for create/update): if field requirements or allowed values are unclear, run jirac issue fields -p PROJ --issue-type TYPE to inspect project-specific custom fields, mandatory fields, and picklist options.
list or search issues: use jirac issue list (assigned to current user), jirac issue list -p PROJ (by project), or jirac issue list --jql 'project = PROJ AND status = "In Progress"' (by JQL). wrap JQL in single quotes (bash) or double quotes with escaped inner quotes (PowerShell).
view issue details: run jirac issue view PROJ-123 for full details. append --versions to include fix-version block and related version info.
create an issue: use jirac issue create -p PROJ for interactive mode, or supply flags: -t TYPE -s "summary" --assignee me --priority High --labels tag1,tag2 --sprint "Sprint N" --field customfield=value. for sub-tasks, add --parent PROJ-100. for bulk creation from manifest, use jirac issue bulk-create --manifest issues.json.
update an issue: run jirac issue update PROJ-123 --summary "new title" --priority High --assignee me --labels backend,api --fix-versions v2.0 --field story_points=8. changes are applied atomically.
transition an issue: use jirac issue transition PROJ-123 for interactive picker, or jirac issue transition PROJ-123 'Done' with explicit transition name. positional argument, not --to flag.
add comment or bulk-comment: run jirac issue comment add PROJ-123 --body "text" for single issue. for bulk, use jirac issue bulk-comment --jql 'project = PROJ AND sprint = openSprints()' --body "text" or --keys PROJ-1,PROJ-2,PROJ-3 --body "text".
attach file: run jirac issue attach PROJ-123 /path/to/file.png. confirm file path and intent before upload.
log work (timetracking): run jirac issue worklog add PROJ-123 --time "2h" --comment "work description". list existing worklogs with jirac issue worklog list PROJ-123. delete with jirac issue worklog delete PROJ-123 <WORKLOG_ID>.
link issues: run jirac issue link list-types to see available link types. create link with jirac issue link add --link-type Blocks PROJ-123 PROJ-456 (PROJ-123 blocks PROJ-456). delete with jirac issue link delete <LINK_ID>.
clone issue: use jirac issue clone PROJ-123 (same project, auto-summary) or jirac issue clone PROJ-123 --project NEWPROJ --summary "Copy: ..." (cross-project).
change issue type: run jirac issue change-type PROJ-123 Bug. uses Jira's native move semantics, preserves issue key.
move issue to different project: run jirac issue move PROJ-123 NEWPROJ. uses Jira's native move semantics, preserves issue key. do not confuse with clone.
delete or archive issue: for single delete, run jirac issue delete PROJ-123 (prompts confirmation) or jirac issue delete PROJ-123 --force. for archive by query, use jirac issue archive --jql 'project = PROJ AND resolution = Done AND updated < -180d'.
bulk operations: use jirac issue bulk-transition --jql '...' --to 'In Progress', jirac issue bulk-update --jql '...' --assignee me --priority High --force, or jirac issue batch --manifest ops.json for mixed create/update/transition/archive ops.
sprint lifecycle: run jirac issue sprints -p PROJ to list sprint states. create with jirac issue sprint-create -p PROJ --name "Sprint 25" --goal "Ship auth v2". start with jirac issue sprint-start <SPRINT_ID>. complete with jirac issue sprint-complete <SPRINT_ID>. update with jirac issue sprint-update <SPRINT_ID> --name "..." --goal "...". delete (destructive) with jirac issue sprint-delete <SPRINT_ID> --force.
view fix versions: run jirac issue versions -p PROJ to browse all versions and backlog preview. filter by version with jirac issue versions -p PROJ --version "v1.2.0".
generate standup/sprint summaries: run jirac issue standup for personal daily update from assigned work. run jirac issue sprint-summary -p PROJ for current sprint rollup, or jirac issue sprint-summary -p PROJ --sprint "Sprint 24" for specific sprint.
scan @mention notifications: run jirac issue notifications to review all Jira @mentions in issue descriptions and comments.
preview markdown rendering: run jirac issue render --input description.md to see how Markdown converts to Jira ADF before sending as description or comment.
open interactive TUI: run jirac tui (default project or assigned issues) or jirac tui -p PROJ for full-featured browse, bulk triage, quick-edit with mouse support (click rows, tabs, pickers; scroll wheel; drag splitter; [?] for help, [🔔] for notifications).
register jirac-mcp into MCP client (optional): run jirac mcp doctor to check prerequisites, then jirac mcp install for interactive client picker (Claude Code, Cursor, etc.), or jirac mcp install --client claude-code for explicit client.
raw Jira REST passthrough (last resort): run jirac api GET /rest/api/3/myself or jirac api POST /rest/api/3/issue --body '{...}' for operations not covered by CLI.
if jirac binary is not installed: prompt user to download from https://github.com/mulhamna/jira-commands/releases and add to PATH.
if jirac auth status fails: user is not authenticated. prompt jirac auth login (interactive) or jirac auth login --profile NAME for named profile setup. do not proceed with issue operations without auth.
if working across multiple Jira instances: before any operation, check active profile with jirac auth profiles and switch with jirac auth use <name> if needed. optionally set JIRAC_PROFILE env var to override at runtime.
if field requirements are unclear (custom fields, mandatory fields, picklists): run jirac issue fields -p PROJ --issue-type TYPE to inspect available fields and constraints. do not guess field names or values.
if target transition status is unknown: use jirac issue transition PROJ-123 (no positional arg) for interactive picker instead of guessing transition name.
if attachment file path is ambiguous or sensitive: confirm full file path and user intent before running jirac issue attach. do not upload without explicit confirmation.
if bulk operation involves destructive actions (delete, archive, bulk-transition, bulk-update, sprint-delete): always confirm intent before --force flag. for bulk-comment or bulk-transition without explicit confirmation, prompt user to review the JQL query first via jirac issue list --jql '...'.
if JQL query contains spaces, parentheses, or quotes: wrap entire --jql value in single quotes (bash) or double quotes with escaped inner quotes (PowerShell). test with jirac issue list --jql '...' first if unsure.
if issue key, project key, status name, or transition name has spaces: wrap in double quotes (e.g., 'project = PROJ AND status = "In Progress"').
if using MCP integration: check that jirac-mcp binary is downloaded separately. run jirac mcp doctor first to verify prerequisites. only then run jirac mcp install.
if network timeout or auth expiry occurs: retry after confirming jirac auth status. if persistent, check Jira instance reachability and token/credential freshness. re-authenticate if needed.
if bulk-create or batch manifest is malformed (invalid JSON, missing required fields): validate manifest structure against bulk-create or batch format spec before execution. jirac will reject invalid manifests.
if issue type, project key, or custom field does not exist: jirac will error. use jirac issue fields -p PROJ --issue-type TYPE or run interactively (jirac issue create -p PROJ) to validate options before scripting.
if result set is empty (no issues matched JQL, no sprints, no versions): operation completes with no changes. check JQL syntax or project scope. do not fail; report to user that no matches were found.
successful issue operations:
for manifest-based operations:
file outputs:
no output contract:
issue created successfully: new issue key is returned (e.g., "PROJ-789") and user can immediately reference it in subsequent operations or view it in Jira UI.
issue updated successfully: jirac confirms field changes (e.g., "updated: priority=High, assignee=user@org.com") and issue is visible in Jira UI with new values.
issue transitioned successfully: new status is confirmed (e.g., "transitioned to Done") and issue workflow state is updated in Jira UI.
comment added successfully: comment ID and timestamp are returned; comment is immediately visible on issue in Jira UI.
attachment uploaded successfully: attachment ID and file name are returned; attachment is visible in issue's attachment section in Jira UI.
bulk operation completed: count of affected issues is returned (e.g., "5 issues updated"). any errors per issue are listed; user can retry failed issues if needed.
sprint created / started / completed / deleted: sprint ID and action confirmation returned; sprint lifecycle state updated in Jira UI and sprint board reflects change.
standup / sprint-summary generated: formatted text or markdown returned to stdout; user sees personal or team work summary ready for sharing.
notifications scanned: list of @mentions returned grouped by issue and commenter; user can triage and respond.
markdown rendered to ADF: preview of Jira ADF (JSON) or HTML output returned; user can validate formatting before submitting as description or comment.
TUI opened: interactive UI displayed with full mouse support; user can browse, triage, and quick-edit issues directly without additional command invocations.
jirac-mcp registered: MCP client (Claude Code, Cursor, etc.) is configured with jirac as available tool; user can invoke jirac commands from within MCP client without CLI.
auth pre-flight passed: jirac --version and jirac auth status both succeed; user is ready to execute issue operations.
auth pre-flight failed: error message indicates missing binary, misconfigured credentials, or unreachable Jira instance; user must remediate (install, login, or check network) before proceeding.