Jira

Jira

Interact with Jira for issue tracking, search, and workflow management.

Installation

1. Install Python dependencies:

   pip install --user requests keyring pyyaml

2. Download the skill from Releases or use directly from this repository.

Setup Verification

After installation, verify the skill is properly configured:

$SKILL_DIR/scripts/jira.py check

This will check:

• Python dependencies (requests, keyring, pyyaml)
• Authentication configuration
• Connectivity to Jira

If anything is missing, the check command will provide setup instructions.

Authentication

Configure Jira authentication using one of these methods:

Option 1: Environment Variables (Recommended)

export JIRA_BASE_URL="https://yourcompany.atlassian.net"
export JIRA_EMAIL="you@example.com"
export JIRA_API_TOKEN="your-token"

Add these to your ~/.bashrc or ~/.zshrc for persistence.

Option 2: Config File

Create ~/.config/agent-skills/jira.yaml:

url: https://yourcompany.atlassian.net
email: you@example.com
token: your-token

Required Credentials

• URL: Your Jira instance URL (e.g., https://yourcompany.atlassian.net)
• Email: Your Atlassian account email
• API Token: Create at https://id.atlassian.com/manage-profile/security/api-tokens

Configuration Defaults

Optionally configure defaults in ~/.config/agent-skills/jira.yaml to reduce repetitive typing:

# Authentication (optional if using environment variables)
url: https://yourcompany.atlassian.net
email: you@example.com
token: your-token

# Optional defaults
defaults:
  jql_scope: "project = DEMO AND assignee = currentUser()"
  security_level: "Internal"
  max_results: 25
  fields: ["summary", "status", "assignee", "priority", "created"]
  custom_fields:
    story_points: "customfield_10028"
    assigned_team: "customfield_12345"
  custom_field_schemas:
    story_points: "number"
    assigned_team: "option"

# Optional project-specific defaults
projects:
  DEMO:
    issue_type: "Task"
    priority: "Medium"
  PROD:
    issue_type: "Bug"
    priority: "High"

How Defaults Work

• CLI arguments always override config defaults
• JQL scope is prepended to all searches: (scope) AND (your_query)
• Security level applies to comments and transitions with comments
• Project defaults apply when creating issues in that project
• Custom fields map friendly names to instance-specific custom field IDs.

These fields are automatically included in API requests and displayed in formatted output. If a mapping is not configured, the skill auto-discovers the field ID and schema type from the Jira API and saves both to the config. Use --set-field NAME=VALUE on issue create and issue update to set custom field values using the friendly name.

• Custom field schemas store the Jira schema type for each custom field

(e.g. number, option, securitylevel). This lets --set-field wrap values correctly (e.g. {"value": "..."} for options) without extra API calls. Schemas are saved automatically during discovery. If missing, run config discover <field_name> to populate them.

View Configuration

# Show all configuration
$SKILL_DIR/scripts/jira.py config show

# Show project-specific defaults
$SKILL_DIR/scripts/jira.py config show --project DEMO

Commands

See permissions.md for read/write classification of each command.

check

Verify configuration and connectivity.

$SKILL_DIR/scripts/jira.py check

This validates:

• Python dependencies are installed
• Authentication is configured
• Can connect to Jira
• API version is detected correctly

search

Search for issues using JQL (Jira Query Language).

$SKILL_DIR/scripts/jira.py search "project = DEMO AND status = Open"
$SKILL_DIR/scripts/jira.py search "assignee = currentUser() ORDER BY updated DESC" --max-results 20

Arguments:

• jql: JQL query string (required unless --contributor is used)
• --contributor: Search for issues where this user is a contributor (reporter, assignee, or commenter). On Jira Cloud, automatically resolves email/name to accountId.
• --project: Project key to scope a --contributor search
• --max-results: Maximum number of results (default: 50)
• --fields: Comma-separated list of fields to include

Deployment-specific queries:

The available JQL functions depend on your Jira deployment type. Run check to see your deployment type and ScriptRunner availability.

• All deployments: See jql-reference.md

for standard JQL patterns (status, dates, fields, ordering).

• Data Center/Server with ScriptRunner: See

scriptrunner.md for advanced functions like linkedIssuesOf(), subtasksOf(), commentedByUser().

• Jira Cloud: ScriptRunner functions are not available. Use the

Cloud-native alternatives documented in jql-reference.md.

issue

Get, create, update, or comment on issues.

# Get issue details
$SKILL_DIR/scripts/jira.py issue get DEMO-123

# Get issue with specific fields only
$SKILL_DIR/scripts/jira.py issue get DEMO-123 --fields "summary,status,assignee"

# Get issue with contributors listed
$SKILL_DIR/scripts/jira.py issue get DEMO-123 --contributors

# List comments on an issue
$SKILL_DIR/scripts/jira.py issue comments DEMO-123
$SKILL_DIR/scripts/jira.py issue comments DEMO-123 --max-results 10

# Create new issue
$SKILL_DIR/scripts/jira.py issue create --project DEMO --type Task --summary "New task"

# Create issue with custom fields
$SKILL_DIR/scripts/jira.py issue create --project DEMO --type Story --summary "New story" --set-field story_points=5

# Update issue
$SKILL_DIR/scripts/jira.py issue update DEMO-123 --summary "Updated summary"

# Update custom fields
$SKILL_DIR/scripts/jira.py issue update DEMO-123 --set-field assigned_team="Platform Team"

# Create issue from a markdown file
$SKILL_DIR/scripts/jira.py issue create --from-file issue.md

# Create issue from file with CLI overrides
$SKILL_DIR/scripts/jira.py issue create --from-file issue.md --priority Critical

# Update issue from a markdown file
$SKILL_DIR/scripts/jira.py issue update DEMO-123 --from-file changes.md

# Create issue with links
$SKILL_DIR/scripts/jira.py issue create --project DEMO --type Task --summary "New task" --link "Blocks:DEMO-456" --link "Relates:DEMO-789"

# Add links to existing issue
$SKILL_DIR/scripts/jira.py issue update DEMO-123 --link "is blocked by:DEMO-456"

# Add comment
$SKILL_DIR/scripts/jira.py issue comment DEMO-123 "This is a comment"

# Add private comment with security level
$SKILL_DIR/scripts/jira.py issue comment DEMO-123 "Internal note" --security-level "Internal"

Arguments for `issue get`:

• issue_key: Issue key (required)
• --fields: Comma-separated list of fields to include (uses config default if not specified)
• --contributors: Show unique contributors (reporter, assignee, comment authors). Opt-in; requires an extra API call.

Arguments for `issue create`:

• --project: Project key (required unless provided in --from-file)
• --type: Issue type (required unless project default configured or provided in --from-file)
• --summary: Issue summary (required unless provided in --from-file)
• --description: Issue description (cannot be used with --from-file)
• --priority: Priority name
• --labels: Comma-separated labels
• --assignee: Assignee account ID
• --set-field NAME=VALUE: Set a custom field (repeatable)
• --from-file PATH: Read issue fields and description from a markdown file (see below)
• --link TYPE:ISSUE: Link to another issue (repeatable). Type can be a name, outward, or inward label (e.g. Blocks, is blocked by, Relates)
• --json: Output as JSON

Arguments for `issue update`:

• issue_key: Issue key (required)
• --summary: New summary
• --description: New description (cannot be used with --from-file)
• --priority: New priority
• --labels: New labels (comma-separated)
• --assignee: New assignee account ID
• --set-field NAME=VALUE: Set a custom field (repeatable)
• --from-file PATH: Read issue fields and description from a markdown file (see below)
• --link TYPE:ISSUE: Link to another issue (repeatable)

Arguments for `issue comments`:

• issue_key: Issue key (required)
• --max-results: Maximum number of comments (default: 50)

Markdown file format for `--from-file`:

The file uses YAML frontmatter (between --- delimiters) for issue fields and the markdown body for the description. CLI arguments override frontmatter values.

---
summary: "Issue title"
project: "DEMO"          # create only; ignored on update
type: "Task"             # create only; ignored on update
priority: "High"
labels:
  - label1
  - label2
assignee: "account-id"
fields:                  # custom fields, same names as --set-field
  story_points: 5
  assigned_team: "Platform"
links:                   # issue links (additive with --link CLI args)
  - blocks: DEMO-456
  - relates to: DEMO-789
  - is cloned by: DEMO-100
---

Markdown body becomes the issue description.
Supports headings, bold, links, lists, and tables.

Link type names can be the type name, outward label, or inward label
(e.g. `blocks`, `is blocked by`, `Relates`). The direction is resolved
automatically based on which label matches.

transitions

Manage issue workflow transitions.

# List available transitions
$SKILL_DIR/scripts/jira.py transitions list DEMO-123

# Transition issue
$SKILL_DIR/scripts/jira.py transitions do DEMO-123 "In Progress"
$SKILL_DIR/scripts/jira.py transitions do DEMO-123 "Done" --comment "Completed"

# Transition with private comment
$SKILL_DIR/scripts/jira.py transitions do DEMO-123 "Done" --comment "Internal resolution notes" --security-level "Internal"

config

Manage configuration and view effective defaults.

# Show all configuration and defaults
$SKILL_DIR/scripts/jira.py config show

# Show project-specific defaults
$SKILL_DIR/scripts/jira.py config show --project DEMO

# Discover and save a custom field mapping
$SKILL_DIR/scripts/jira.py config discover story_points
$SKILL_DIR/scripts/jira.py config discover security_level

This displays:

• Authentication settings (with masked token)
• Default JQL scope, security level, max results, and fields
• Project-specific defaults for issue type and priority

`config discover` takes a snake_case friendly name, queries the Jira API for a matching field (underscores become spaces for matching, case-insensitive), and saves the mapping to ~/.config/agent-skills/jira.yaml under defaults.custom_fields.

fields

List available fields in your Jira instance.

# List all global fields
$SKILL_DIR/scripts/jira.py fields

# List fields for specific project and issue type
$SKILL_DIR/scripts/jira.py fields --project DEMO --issue-type Task

Arguments:

• --project: Project key for context-specific fields
• --issue-type: Issue type name (requires --project)

Note: Fields vary by project and issue type. When creating or searching issues, use --project and --issue-type to see only the fields available in that context.

statuses

List available statuses and status categories.

# List all statuses
$SKILL_DIR/scripts/jira.py statuses

# List status categories (To Do, In Progress, Done)
$SKILL_DIR/scripts/jira.py statuses --categories

Arguments:

• --categories: Show status categories instead of individual statuses

Recommendation: Use statusCategory in JQL queries for more portable queries:

• statusCategory = "To Do" - matches all statuses in the To Do category
• statusCategory = "In Progress" - matches all in-progress statuses
• statusCategory = Done - matches all completed statuses

This is more reliable than using specific status names, which vary between projects.

user

Search for Jira users by email, name, or username. On Jira Cloud, returns accountId values needed for JQL queries.

# Search by email
$SKILL_DIR/scripts/jira.py user search "jdoe@example.com"

# Search by display name
$SKILL_DIR/scripts/jira.py user search "Jane Doe"

Arguments for `user search`:

• query: Email, display name, or username to search for

collaboration

Discover collaboration patterns across issues and epics.

# Find epics with multiple contributors (assignees)
$SKILL_DIR/scripts/jira.py collaboration epics --project DEMO

# Require at least 3 contributors
$SKILL_DIR/scripts/jira.py collaboration epics --project DEMO --min-contributors 3

# Limit number of epics checked
$SKILL_DIR/scripts/jira.py collaboration epics --max-results 20

Arguments for `collaboration epics`:

• --project: Project key to scope the search
• --min-contributors: Minimum unique assignees to qualify (default: 2)
• --max-results: Maximum epics to check (default: 50)

Note: This makes N+1 API calls (1 for epics + 1 per epic for children). Use --max-results to control cost.

automations

List and inspect Jira automation rules. Uses the Automation Rule Management API via the gateway path, reusing existing Jira Cloud credentials. Cloud-only — Data Center and Server instances will receive a clear error.

# List all automation rules
$SKILL_DIR/scripts/jira.py automations list

# List rules scoped to a specific project
$SKILL_DIR/scripts/jira.py automations list --project OSPRH

# List only enabled rules
$SKILL_DIR/scripts/jira.py automations list --state ENABLED

# Get full details of a rule (triggers, conditions, actions)
$SKILL_DIR/scripts/jira.py automations get <rule-uuid>

Arguments for `automations list`:

• --project: Filter to rules scoped to this project key
• --state: Filter by state (ENABLED or DISABLED)
• --limit: Maximum rules to return (default: 100)

Arguments for `automations get`:

• uuid (positional): Automation rule UUID (shown in list output)

The get command renders a markdown document describing the rule step by step: metadata, trigger, conditions, actions, branches, and external connections. Component types are translated to human-readable labels (e.g., jira.issue.event.trigger:created → "Issue created") and value configurations are summarised inline.

Note: The automation API requires the Atlassian Cloud ID, which is fetched automatically from _edge/tenant_info and cached for the session.

Examples

Create and verify an issue

# Create the issue
$SKILL_DIR/scripts/jira.py issue create \
  --project DEMO \
  --type Bug \
  --summary "Login button not working" \
  --description "The login button on the homepage does not respond to clicks."

# Verify it was created correctly
$SKILL_DIR/scripts/jira.py issue get DEMO-456

Move issue through workflow

# Check available transitions first
$SKILL_DIR/scripts/jira.py transitions list DEMO-123

# Start work on an issue
$SKILL_DIR/scripts/jira.py transitions do DEMO-123 "In Progress"

# Verify the transition
$SKILL_DIR/scripts/jira.py issue get DEMO-123 --fields "summary,status"

See examples.md for more usage patterns.

JQL Reference

Common JQL queries and patterns: see jql-reference.md.

Quick reference — combine with AND, OR, and ORDER BY:

assignee = currentUser() AND statusCategory != Done ORDER BY priority DESC

Use statusCategory ("To Do", "In Progress", Done) for queries that work across projects.

Model Guidance

This skill makes API calls requiring structured input/output. A standard-capability model is recommended.

Troubleshooting

Check command fails

Run $SKILL_DIR/scripts/jira.py check to diagnose issues. It will provide specific error messages and setup instructions.

Authentication failed

1. Verify your API token is correct 2. Ensure you're using your email (not username) 3. For Jira Cloud, use your Atlassian account email 4. For Jira Data Center/Server, use your username

Permission denied

You may not have access to the requested project or issue. Contact your Jira administrator.

JQL syntax error

Use the Jira web interface to test your JQL query before using it in scripts.

Import errors

Ensure dependencies are installed:

pip install --user requests keyring pyyaml

Jira Skill Examples

Detailed usage examples for common Jira workflows.

Find My Open Issues

$SKILL_DIR/scripts/jira.py search "assignee = currentUser() AND status != Done ORDER BY priority DESC"

Create a Bug Report

# Create the bug
$SKILL_DIR/scripts/jira.py issue create \
  --project DEMO \
  --type Bug \
  --summary "Login button not working" \
  --description "The login button on the homepage does not respond to clicks."

# Verify it was created correctly
$SKILL_DIR/scripts/jira.py issue get DEMO-456

Move Issue Through Workflow

# Check available transitions first
$SKILL_DIR/scripts/jira.py transitions list DEMO-123

# Start work on an issue
$SKILL_DIR/scripts/jira.py transitions do DEMO-123 "In Progress"

# Verify the transition
$SKILL_DIR/scripts/jira.py issue get DEMO-123 --fields "summary,status"

# Complete the issue
$SKILL_DIR/scripts/jira.py transitions do DEMO-123 "Done" --comment "Implemented and tested"

# Verify completion
$SKILL_DIR/scripts/jira.py issue get DEMO-123 --fields "summary,status"

Add Private Comment

# Add comment visible only to specific security level
$SKILL_DIR/scripts/jira.py issue comment DEMO-123 \
  "This is sensitive internal information" \
  --security-level "Internal"

# Verify comment was added
$SKILL_DIR/scripts/jira.py issue comments DEMO-123 --max-results 1

View Comments on an Issue

$SKILL_DIR/scripts/jira.py issue comments DEMO-123

Find Issues by Contributor

# Find all issues where jsmith is reporter, assignee, or commenter
$SKILL_DIR/scripts/jira.py search --contributor "jsmith" --project DEMO

Find Collaborative Epics

# Find epics in DEMO project with 2+ assignees on child issues
$SKILL_DIR/scripts/jira.py collaboration epics --project DEMO

# Require at least 3 contributors
$SKILL_DIR/scripts/jira.py collaboration epics --project DEMO --min-contributors 3

Search with Specific Fields

$SKILL_DIR/scripts/jira.py search \
  "project = DEMO AND created >= -7d" \
  --fields "key,summary,status,assignee,created"

Using Configuration Defaults

With defaults configured (see SKILL.md Configuration Defaults):

# Search uses JQL scope automatically
$SKILL_DIR/scripts/jira.py search "status = Open"
# Becomes: (project = DEMO AND assignee = currentUser()) AND (status = Open)

# Create issue uses project defaults
$SKILL_DIR/scripts/jira.py issue create --project DEMO --summary "Fix login bug"
# Automatically uses issue_type="Task" and priority="Medium" from DEMO defaults

# Comments use default security level
$SKILL_DIR/scripts/jira.py issue comment DEMO-123 "Internal note"
# Automatically applies security_level="Internal"

# Override defaults when needed
$SKILL_DIR/scripts/jira.py search "status = Open" --max-results 100
# CLI argument overrides the configured default of 25

JQL Reference

Common JQL queries for use with the Jira skill.

Basic Queries

Combine with AND, OR, and use ORDER BY for sorting.

Status Categories

Jira organizes all statuses into three categories. Use statusCategory for queries that work across projects:

Example: Instead of status = "Open" OR status = "Backlog", use statusCategory = "To Do".

Use $SKILL_DIR/scripts/jira.py statuses --categories to see all status categories in your Jira instance.

Date Functions

Useful Patterns

# My open issues, highest priority first
assignee = currentUser() AND statusCategory != Done ORDER BY priority DESC

# Recently updated in a project
project = DEMO AND updated >= -7d ORDER BY updated DESC

# Unassigned bugs
project = DEMO AND issuetype = Bug AND assignee is EMPTY

# Issues created this sprint
project = DEMO AND sprint in openSprints()

# High priority items not yet started
priority in (High, Highest) AND statusCategory = "To Do"

Cloud Alternatives

These standard JQL patterns replace ScriptRunner functions that are only available on Data Center/Server.

Finding linked issues

ScriptRunner: issue in linkedIssuesOf("PROJ-123")

Cloud alternative: Use issue get PROJ-123 to read the issue's links, then search by the linked issue keys directly.

Finding subtasks

ScriptRunner: issue in subtasksOf("PROJ-123")

Cloud alternative: parent = PROJ-123

Finding parent issues

ScriptRunner: issue in parentsOf("PROJ-123")

Cloud alternative: Use issue get PROJ-123 to read the parent field.

Finding epic children

ScriptRunner: issue in issuesInEpics("EPIC-123")

Cloud alternative: "Epic Link" = EPIC-123 or parentEpic = EPIC-123

Finding issues by commenter

ScriptRunner: issue in commentedByUser("accountId")

Cloud alternative: No direct JQL equivalent. Use the --contributor flag which searches reporter and assignee fields.

Command Permissions

This reference classifies commands by access level to help agents enforce appropriate permission controls.

• read: Safe to execute without user confirmation. These commands

only retrieve or display information.

• write: Requires user confirmation before execution. These

commands create, modify, or delete data.

ScriptRunner Enhanced Search Guide

Data Center/Server only. ScriptRunner Enhanced Search functions

are not available on Jira Cloud. If you are using Jira Cloud, see

jql-reference.md for

alternative query patterns.

ScriptRunner Enhanced Search provides advanced JQL functions for complex queries that aren't possible with standard JQL. These functions require the ScriptRunner plugin on a Jira Data Center/Server instance.

Availability

ScriptRunner is available on Jira Data Center/Server as a self-hosted plugin. The Jira skill automatically detects whether ScriptRunner is available and will reject queries that use ScriptRunner functions if the plugin is not installed.

User Lookup for Advanced Queries

Many ScriptRunner functions require user identifiers. Users are typically known by email or username, not internal account IDs.

Finding User Account IDs

Before using user-based ScriptRunner functions, look up the user's account ID:

# Search for user by email or display name
python jira.py search "assignee = 'user@example.com'"

# Or use Jira's user search API
# The response includes accountId field needed for ScriptRunner queries

Note: In Cloud, users are identified by accountId. In Data Center/Server, they may use username or key.

Available Functions

Link-Related Functions

Find issues based on link relationships:

# Find all issues linked to a specific issue
python jira.py search 'issue in linkedIssuesOf("DEMO-123")'

# Find all linked issues recursively (includes links of links)
python jira.py search 'issue in linkedIssuesOfAll("DEMO-123")'

# Find issues with specific link types
python jira.py search 'issue in hasLinkType("Dependency")'
python jira.py search 'issue in hasLinkType("Blocks")'
python jira.py search 'issue in hasLinkType("Relates")'

# Find issues that have any links
python jira.py search 'issue in hasLinks()'

# Find issues with remote links (external URLs)
python jira.py search 'issue in issuesWithRemoteLinks()'
python jira.py search 'issue in hasRemoteLinks()'

Common link types:

• Blocks / is blocked by
• Dependency / depends on
• Relates / relates to
• Cloners / is cloned by
• Duplicate / duplicates

Hierarchy Functions

Navigate parent/child and epic relationships:

# Find all subtasks of an issue
python jira.py search 'issue in subtasksOf("DEMO-123")'

# Find parent issues
python jira.py search 'issue in parentsOf("DEMO-456")'

# Find issues that have subtasks
python jira.py search 'project = DEMO AND issue in hasSubtasks()'

# Find the epic for specific issues
python jira.py search 'issue in epicsOf("DEMO-123")'

# Find all issues in specific epics
python jira.py search 'issue in issuesInEpics("EPIC-123")'
python jira.py search 'issue in issuesInEpics("EPIC-123", "EPIC-456")'

Comment and User Activity Functions

Find issues based on comments and user interactions:

# IMPORTANT: First look up the user's account ID
# For Cloud (uses accountId):
python jira.py search "assignee = 'user@example.com'" --fields accountId
# Note the accountId from the response, e.g., "5b10a2844c20165700ede21g"

# Then use it in ScriptRunner queries:
python jira.py search 'issue in commentedByUser("5b10a2844c20165700ede21g")'

# For Data Center/Server (uses username):
python jira.py search 'issue in commentedByUser("jsmith")'

# Find issues that have comments
python jira.py search 'issue in issuesWithComments()'

# Find issues last updated by a user
python jira.py search 'issue in lastUpdatedBy("5b10a2844c20165700ede21g")'

Workflow for finding issues commented on by a user:

1. Identify the user by a known attribute (email, display name) 2. Look up their accountId (Cloud) or username (DC/Server) 3. Use the identifier in ScriptRunner query

Example:

# Step 1: Find the user's account ID
python jira.py search "assignee = 'john.smith@example.com'" --fields accountId --max-results 1

# Step 2: Use the account ID in ScriptRunner query
python jira.py search 'issue in commentedByUser("5b10a2844c20165700ede21g") AND project = DEMO'

Workflow Transition Functions

Track issue status changes:

# Find issues that have been transitioned
python jira.py search 'issue in transitionedIssues()'

# Find issues transitioned by a specific user
python jira.py search 'issue in transitionedBy("5b10a2844c20165700ede21g")'

# Find issues transitioned from a specific status
python jira.py search 'issue in transitionedFrom("In Progress")'

# Find issues transitioned to a specific status
python jira.py search 'issue in transitionedTo("Done")'

# Combine for complex queries
python jira.py search 'issue in transitionedFrom("In Progress") AND issue in transitionedTo("Done") AND updated >= -7d'

Field-Based Functions

Query based on custom field values:

# Find issues with specific field values
python jira.py search 'issue in issuesWithFieldValue("customfield_10001", "value")'

# Find issues that have a value in a specific field
python jira.py search 'issue in hasFieldValue("Story Points")'

# Find recently updated issues
python jira.py search 'issue in lastUpdated("7d")'

General Purpose Functions

Advanced expression-based queries:

# Use custom expressions (advanced)
python jira.py search 'issue in expression("issue.assignee == currentUser()")'

# Search issues with custom logic
python jira.py search 'issue in searchIssues("project = DEMO AND priority = High")'

Practical Examples

Find all dependencies for a feature

# Find all issues that DEMO-123 depends on
python jira.py search 'issue in linkedIssuesOf("DEMO-123") AND issuelinktype = "Dependency"'

# Find what depends on DEMO-123
python jira.py search 'issue in linkedIssuesOf("DEMO-123") AND issuelinktype = "is depended on by"'

Track epic progress

# Find all incomplete issues in an epic
python jira.py search 'issue in issuesInEpics("EPIC-123") AND status != Done'

# Count subtasks by status
python jira.py search 'issue in subtasksOf("STORY-456") AND status = "In Progress"'

Audit user activity

# Find all issues a user commented on this week
# (First look up accountId as shown in Comment Functions section)
python jira.py search 'issue in commentedByUser("ACCOUNT_ID") AND updated >= -7d'

# Find issues transitioned by a user today
python jira.py search 'issue in transitionedBy("ACCOUNT_ID") AND updated >= startOfDay()'

Find blocked work

# Find all issues blocked by open issues
python jira.py search 'issuelinktype = "is blocked by" AND issue in linkedIssuesOf(status = Open)'

Troubleshooting

Function Not Found Error

Error: Function 'linkedIssuesOf' not found

Solution: ScriptRunner Enhanced Search is not available on your Jira instance. Run check to verify your deployment type and ScriptRunner availability. If you are using Jira Cloud, see jql-reference.md for alternative query patterns.

Invalid User Identifier

Error: Query returns no results or "User not found"

Solution: Verify you're using the correct identifier type:

• Cloud: Use accountId (e.g., "5b10a2844c20165700ede21g")
• Data Center/Server: Use username (e.g., "jsmith")

Look up the user first:

python jira.py search "assignee = 'user@example.com'" --fields accountId,name

Performance Issues

Tip: ScriptRunner functions can be slow on large instances. Combine with filters:

# Good: Scoped to recent issues
python jira.py search 'issue in linkedIssuesOf("DEMO-123") AND updated >= -30d'

# Less optimal: Scans all history
python jira.py search 'issue in linkedIssuesOf("DEMO-123")'

Reference

For complete ScriptRunner documentation, see:

• ScriptRunner JQL Functions Reference
• Cloud vs Server Differences