Skip to content

JQL

JQL (Jira Query Language) is Atlassian's filter syntax. jira-cli reaches it three ways:

Approach When to use
issue list filter flags Common case. The CLI assembles the JQL from --project, --status, etc.
jira jql build Same flag surface, but prints the JQL instead of running it. Useful as a preview, or as a starting point for a saved query.
search jql Hand-written JQL when the flag set can't express what you need.

jira issue list starts from a bounded default query:

updated >= -365d ORDER BY updated DESC

Pass --assignee me to scope that default to issues assigned to you, or hand-write the full query via --jql:

jira issue list --jql 'project = <PROJECT_KEY> AND status = "In Progress"'

build

Assemble a JQL string from the same filter flags issue list accepts, without calling Jira. Use it to preview the query a set of flags resolves to before running a heavy search, or as a building block for a saved query. See Builder coverage for the full flag set and current limits.

jira jql build --project <PROJECT_KEY> --assignee me --priority Medium
jira jql build --key <PROJECT_KEY>-1:10,<OTHER_PROJECT_KEY>-1:12
jira jql build --project <PROJECT_KEY> --desc=false
jira jql build                                        # no filters: defaults

INF ℹ️ board_scope.applied=false jql="project = <PROJECT_KEY> AND assignee = currentUser() AND priority = Medium ORDER BY updated DESC" precedence=none

{
  "ok": true,
  "meta": { "command": "jql.build", "timestamp": "…", "request_id": "…" },
  "data": {
    "board_scope": { "applied": false },
    "jql": "project = <PROJECT_KEY> AND assignee = currentUser() AND priority = Medium ORDER BY updated DESC",
    "precedence": "none"
  },
  "errors": [],
  "warnings": []
}

Defaults

  • No filters: updated >= -365d ORDER BY updated DESC.
  • Sort defaults to descending. --desc (default): ORDER BY <field> DESC. Pass --desc=false for ascending.
  • --order-by: defaults to updated; other values are created, priority, status, key, summary.

Builder coverage

Work in progress

The builder is intentionally limited today; the flag set will grow over time. Anything outside what's listed below (raw clauses, date ranges, custom fields, IN (…) literals, NOT, OR, parentheses) needs hand-written JQL via search jql. File what you need.

Builder flags map to documented Jira JQL concepts:

  • Fields: --project, --epic, --assignee, --reporter, --key, --status, --priority, --label, --type, --board, --board-id
  • Sort: --order-by <field>, --desc=false for ascending order
  • Operators applied: =, IN (...) (for repeated flag values), is EMPTY
  • Keywords/functions: AND, ORDER BY, currentUser() (via --assignee me or --reporter me)

Issue key ranges

--key accepts single issue keys, comma lists, repeated flags, and inclusive ranges:

jira jql build --key <ISSUE_KEY>
jira jql build --key <ISSUE_KEY>,<OTHER_ISSUE_KEY>
jira jql build --key <PROJECT_KEY>-1:10,<OTHER_PROJECT_KEY>-1:12
jira jql build --key <PROJECT_KEY>-1..10 --key <OTHER_PROJECT_KEY>-1..12

Each comma member is parsed independently. Lists and repeated flags may mix projects, but one range may not span projects: <PROJECT_KEY>-1:<OTHER_PROJECT_KEY>-100 is rejected instead of crossing project prefixes. Keep comma lists tight (<ISSUE_KEY>,<OTHER_ISSUE_KEY>); whitespace inside a --key expression is not accepted.

See also