jira-search-jql

jira-search

Query and discovery operations for JIRA issues using JQL (JIRA Query Language).

Risk Levels

Risk Legend: - Safe, read-only | ! Caution, modifiable | !! Warning, destructive but recoverable | !!! Danger, irreversible

When to use this skill

Perfect for:

• Search by criteria: "Find all bugs assigned to me in the current sprint"
• Reporting: Export sprint results or metrics to CSV/JSON
• Bulk operations: Update labels, priority, or assignee on 50+ issues at once
• Automation: Create saved filters for monitoring or dashboards

Not ideal for:

• Single issue operations - Use jira-issue skill
• Workflow transitions on many issues - Use jira-lifecycle skill
• Complex issue relationships - Use jira-relationships skill
• Sprint/board management - Use jira-agile skill

Quick Start

# Find your open issues
jira-as search query "assignee = currentUser() AND status != Done"

# Find bugs in a project
jira-as search query "project = PROJ AND type = Bug AND status = Open"

# Export results to CSV
jira-as search export "project = PROJ" --output report.csv

# Save a filter for reuse
jira-as search filter create "My Bugs" "type = Bug AND assignee = currentUser()" --favourite

For detailed setup, see docs/QUICK_START.md.

Available Commands

IMPORTANT: Always use the jira-as CLI. Never run Python scripts directly.

All commands support --help for full documentation.

What this skill does

1. JQL Search: Execute custom queries with sorting, pagination, field selection
2. JQL Builder: Build and validate queries interactively
3. Query History: Save queries locally for quick reuse
4. Saved Filters: Full CRUD on JIRA filters with sharing
5. Filter Subscriptions: View email subscriptions on filters
6. Export Results: CSV, JSON, JSON Lines with streaming for large datasets
7. Bulk Updates: Update multiple issues from search results

Common Options

Examples by Category

Search

# Basic search
jira-as search query "project = PROJ AND status = Open"

# With field selection
jira-as search query "project = PROJ" --fields key,summary,status,assignee

# With result limit
jira-as search query "project = PROJ" --max-results 50

JQL Building

# Validate syntax
jira-as search validate "project = PROJ AND status = Open"

# Build JQL from options
jira-as search build --project PROJ --status Open --assignee currentUser()

# Get field suggestions
jira-as search suggest --field status
jira-as search suggest --field status --prefix "In"
jira-as search suggest --field assignee --prefix "john"

# List available fields and operators
jira-as search fields

# List available JQL functions
jira-as search functions

Saved Filters

# Create filter
jira-as search filter create "Sprint Issues" "sprint IN openSprints()" --favourite

# List filters
jira-as search filter list --favourite

# Run filter (by filter ID)
jira-as search filter run 10042

# Share filter
jira-as search filter share 10042 --project PROJ

# Delete filter
jira-as search filter delete 10042 --force

Export

# CSV export
jira-as search export "project = PROJ" -o report.csv

# JSON export
jira-as search export "project = PROJ" -o data.json --format json

# Export specific fields
jira-as search export "project = PROJ" -o report.csv --fields key,summary,status,assignee

# Limit results
jira-as search export "project = PROJ" -o report.csv --max-results 500

Using Filters in Queries

# Run a query using a saved filter ID
jira-as search query --filter 10042

# Combine filter with additional criteria
jira-as search query --filter 10042 --max-results 100

# Save search results as a new filter
jira-as search query "project = PROJ" --save-as "My New Filter"

Exporting Large Datasets

For large exports, optimize your query and field selection:

# Large export with minimal fields for speed
jira-as search export "project = PROJ" -o report.csv --fields key,summary,status,assignee

# Split by time periods for very large datasets
jira-as search export "project = PROJ AND created >= -30d" -o recent.csv
jira-as search export "project = PROJ AND created >= -60d AND created < -30d" -o older.csv

Exit Codes

Troubleshooting

Quick diagnostics:

jira-as search validate "your query"     # Check syntax
jira-as search fields                    # List available fields
jira-as search suggest --field status    # Get valid values for a field
jira-as search functions                 # List available JQL functions

For detailed troubleshooting, see references/TROUBLESHOOTING.md.

Configuration

Requires JIRA credentials via environment variables (JIRA_SITE_URL, JIRA_EMAIL, JIRA_API_TOKEN).

Documentation

Templates

Pre-configured JQL templates:

• assets/templates/jql_templates.json - Common search patterns
• assets/ERROR_SOLUTIONS.json - Error catalog

Related skills

• jira-issue: For creating and updating individual issues
• jira-lifecycle: For transitioning issues found in searches
• jira-collaborate: For bulk commenting on search results
• jira-agile: For sprint and board operations
• jira-relationships: For issue linking and dependencies
• jira-bulk: For large-scale bulk operations