JQL Guide
JQL (Jira Query Language) is used by manage_search to find issues. This guide covers the most useful patterns for both CLI and MCP usage.
Basic Syntax
Section titled “Basic Syntax”JQL queries follow the pattern: field operator value
project = "PROJ" AND status = "In Progress"Use AND, OR, and NOT to combine conditions, and ORDER BY for sorting.
Operators
Section titled “Operators”| Operator | Description | Example |
|---|---|---|
= | Exact match | status = "Done" |
!= | Not equal | status != "Closed" |
~ | Contains text | summary ~ "bug fix" |
!~ | Does not contain | summary !~ "test" |
IN | Match any in list | status IN ("Open", "In Progress") |
NOT IN | Not in list | priority NOT IN ("Low", "Lowest") |
IS EMPTY | Null / unset | assignee IS EMPTY |
IS NOT EMPTY | Not null | assignee IS NOT EMPTY |
>, <, >=, <= | Comparison | created >= "2025-01-01" |
Common Fields
Section titled “Common Fields”| Field | Description | Example |
|---|---|---|
project | Project key | project = "PROJ" |
status | Issue status | status = "In Progress" |
assignee | Assigned user | assignee = currentUser() |
reporter | Issue creator | reporter = "jane@example.com" |
priority | Priority level | priority = "High" |
type / issuetype | Issue type | type = "Bug" |
labels | Issue labels | labels = "frontend" |
components | Issue components | component = "API" |
fixVersion | Fix version | fixVersion = "v2.0.0" |
sprint | Sprint name | sprint = "Sprint 42" |
sprint in openSprints() | Active sprints | sprint in openSprints() |
created | Creation date | created >= "-7d" |
updated | Last modified | updated >= "-24h" |
resolved | Resolution date | resolved >= startOfMonth() |
due | Due date | due <= endOfWeek() |
resolution | Resolution type | resolution = EMPTY (unresolved) |
text | Full-text search | text ~ "database migration" |
Date Functions
Section titled “Date Functions”| Function | Description | Example |
|---|---|---|
currentUser() | Logged-in user | assignee = currentUser() |
startOfDay() | Start of today | created >= startOfDay() |
startOfWeek() | Start of this week | updated >= startOfWeek() |
startOfMonth() | Start of this month | resolved >= startOfMonth() |
endOfDay() | End of today | due <= endOfDay() |
endOfWeek() | End of this week | due <= endOfWeek() |
now() | Current timestamp | updated >= "-1h" |
Relative Dates
Section titled “Relative Dates”Use relative date syntax for reusable queries:
| Syntax | Meaning |
|---|---|
"-1h" | 1 hour ago |
"-7d" | 7 days ago |
"-2w" | 2 weeks ago |
"-1M" | 1 month ago |
Practical Patterns
Section titled “Practical Patterns”My open issues (prioritized)
Section titled “My open issues (prioritized)”assignee = currentUser() AND resolution = EMPTY ORDER BY priority DESCSprint burndown
Section titled “Sprint burndown”sprint in openSprints() AND project = "PROJ" ORDER BY rank ASCRecent bugs
Section titled “Recent bugs”type = Bug AND created >= "-7d" ORDER BY created DESCUnassigned high-priority items
Section titled “Unassigned high-priority items”assignee IS EMPTY AND priority IN ("High", "Highest") AND resolution = EMPTY ORDER BY created ASCIssues updated today
Section titled “Issues updated today”updated >= startOfDay() AND project = "PROJ" ORDER BY updated DESCOverdue issues
Section titled “Overdue issues”due < now() AND resolution = EMPTY ORDER BY due ASCCross-project search
Section titled “Cross-project search”project IN ("PROJ", "DEVOPS", "INFRA") AND status = "In Progress" ORDER BY updated DESCFull-text search
Section titled “Full-text search”text ~ "database migration" ORDER BY relevance DESCIssues resolved this sprint
Section titled “Issues resolved this sprint”sprint in openSprints() AND status = Done ORDER BY resolutiondate DESCIssues with no fix version
Section titled “Issues with no fix version”project = "PROJ" AND fixVersion IS EMPTY AND resolution = EMPTY ORDER BY priority DESCBugs by component
Section titled “Bugs by component”project = "PROJ" AND type = Bug AND component = "API" ORDER BY priority DESCRecently transitioned to Done
Section titled “Recently transitioned to Done”status changed TO "Done" AFTER "-7d" ORDER BY updated DESCUsing JQL with jtk
Section titled “Using JQL with jtk”jtk issues search 'assignee = currentUser() AND status != Done ORDER BY priority DESC'{ "action": "jql", "jql": "project = PROJ AND sprint in openSprints() ORDER BY rank ASC", "max_results": 50}