Jira

Imported from open-cli-collective/atlassian-cli (skills/Jira/SKILL.md). Install upstream with npx skills add open-cli-collective/atlassian-cli --skill Jira. Copyright stays with the author.

Jira

Skill expects: jtk v1.0.84+

Issue tracking and project management via the jtk CLI tool (open-cli-collective/atlassian-cli).

Prerequisites

All workflows share these prerequisites. Workflows do not repeat them — check these before entering any workflow.

1. jtk installed — verify with jtk --version
2. Auth configured — run jtk init to set up interactively. Verify with jtk config test (reports connection + identity). Run jtk config show to see the resolved config file path on your system (typical locations: ~/.config/jira-ticket-cli/config.json on Linux, ~/Library/Application Support/jira-ticket-cli/config.json on macOS).
3. Environment-variable auth (alternative to config file) — precedence: JIRA_* env vars → ATLASSIAN_* env vars → config file. Use ATLASSIAN_URL / ATLASSIAN_EMAIL / ATLASSIAN_API_TOKEN for credentials shared with cfl (Confluence CLI); use JIRA_* to override per-tool. Bearer auth additionally requires JIRA_CLOUD_ID (or ATLASSIAN_CLOUD_ID) — find the Cloud ID at https://your-site.atlassian.net/_edge/tenant_info.
4. Defaults for missing inputs — see the Defaults & Missing Inputs section below.

Defaults & Missing Inputs

When the user's request doesn't specify a required input (project key, board ID, etc.), consult jtk's own defaulting mechanisms before asking. If the input is still missing, ask the user — and suggest the one-time setup that would persist the default.

Project key

Resolution order jtk uses: --project flag → JIRA_DEFAULT_PROJECT env var → default_project in config file.

If still missing: ask the user. Then suggest they persist it:

• Env var (per-shell): export JIRA_DEFAULT_PROJECT=PROJ — add to .bashrc / .zshrc / equivalent to persist
• Config file: edit the default_project field in the file shown by jtk config show

Env var wins over config. Once set, jtk issues list (and other project-scoped commands) work without --project.

Board (ID or name)

jtk has no default-board mechanism — there's no env var or config key for a default board. If a board is needed and the user hasn't provided one, ask which board. Suggest jtk boards list or jtk boards list --project KEY to discover boards. The --board flag (and board-accepting positional arguments) accept either a numeric ID or a board name — names are resolved via the local cache (see Cache Warming).

Sprint (ID or name), issue key, attachment ID, comment ID, etc.

No defaults exist. Ask the user. Do not guess. Sprint-accepting arguments (jtk sprints add, --sprint on list) accept either a numeric ID or a sprint name — names are resolved via the local cache (see Cache Warming).

Assignee / user identity shortcut

For assignment and self-scoped queries, --assignee me resolves to the authenticated user — no account ID lookup needed. jtk me --id returns the current user's account ID when a raw ID is specifically needed (e.g., embedding in a script or passing to an API-boundary tool that can't consume an email or display name). For regular assign/unassign, just use --assignee me — both jtk issues update and jtk issues assign accept it directly via their resolver.

Cache Warming (first use per session)

jtk caches instance metadata locally — fields, projects, users, issue types, statuses, priorities, resolutions, boards, and link types — to avoid repeated API calls on every invocation. When a session first exercises a workflow that depends on a cold cache (creating issues, creating links, moving issues between projects, resolving user identities for assignment, etc.), the command will fail with an actionable error like cannot resolve link type "X" from cache — run 'jtk refresh linktypes' or cannot resolve issue type ID for "Task" in project KEY from cache — run 'jtk refresh issuetypes'.

To avoid hitting this mid-workflow, warm the caches once near the start of any session that will do significant write work or user lookups:

jtk refresh          # refresh everything (recommended)

Or refresh just the resources you expect to touch:

jtk refresh linktypes issuetypes users

Both forms are idempotent and fast. Bare jtk refresh is the simplest — it fetches every cacheable resource and auto-resolves dependencies; on a warm cache it's cheap. Repeated refreshes within a session are fine. If a command fails mid-run with run jtk refresh <resource>, run the suggested refresh (or bare jtk refresh) and retry.

Use jtk refresh --status to inspect cache freshness without fetching anything.

Common Errors

Common Patterns

Output Contract

jtk commands follow a text-first output model (per the repo's Output Artifact Contract):

• --fields <csv> — explicitly selects supported fields on commands that expose field projection.
• --fulltext — disables truncation of descriptions and comments without changing list output shape. Use when the user needs full body content (e.g., "show the full description").
• --id — emits only the primary identifier (issue key, account ID, etc.) and takes precedence over --fulltext and --fields (projection is bypassed entirely). Stdout is identifier-only, one per line, safe to pipe; any continuation notice goes to stderr.

automation export is the only resource command that emits JSON (set-credential --json is the control-plane exception). For every other command, use --id for scripting composition.

Pagination & Result Sizing

Most list-type commands (jtk issues list, jtk issues search, jtk projects list, jtk comments list, jtk sprints list, jtk boards list, jtk users search, jtk dashboards list, etc.) accept --max N as the size of one page (default 50). Commands that paginate also accept --next-page-token TOKEN to resume. Each invocation emits one page. A "More results available" notice and its token go to stderr; stdout stays data-only, including under --id.

Extracting Issue Keys from URLs

Many commands take an issue key (PROJ-123). If the user provides a browse URL, the key is the segment after /browse/:

https://INSTANCE.atlassian.net/browse/PROJ-123
                                       ^^^^^^^^

Use that key directly — no API lookup needed.

Workflow Routing

Quick Reference

Full CLI reference: load CliReference.md

Examples

Example 1: Quick status check

User: "What am I working on in Jira?"
→ Invokes QuickStatus workflow
→ Searches for issues assigned to current user in active statuses
→ Returns grouped list by status

Example 2: Create and assign a bug

User: "Create a bug in PROJ for broken login page, assign to me"
→ Invokes ManageIssue workflow
→ Creates issue with --type Bug --summary "Broken login page" --assignee me
→ Returns issue key and link

Example 3: Search with JQL

User: "Find all high priority issues in PROJ updated this week"
→ Invokes SearchIssues workflow
→ Runs: jtk issues search --jql "project = PROJ AND priority = High AND updated >= -7d"
→ Returns formatted results