Run and Save Jira JQL Queries from the Command Line

atlassian-cli is an independent, community open-source project, not affiliated with, endorsed by, or sponsored by Atlassian, and is not Atlassian's official CLI (acli). Product names are used only to identify compatibility.

To run a Jira JQL query from the command line, pass the query string to atlassian-cli jira issue search --jql. The CLI sends your JQL to the Jira Cloud search API and prints the matching issues as a table, JSON, CSV, YAML, or markdown. That is the whole idea, and everything below builds on it.

This post is not a JQL syntax reference. If you want operators, functions, and field examples, read the JQL query cheat sheet. Here the focus is the mechanics of running JQL from a terminal: shaping the output, piping results into other tools, and saving the queries you run every day so you never retype them. All commands use atlassian-cli, an independent open-source binary that talks to the same public REST APIs the Jira web UI uses.

Run a Jira JQL query from the command line

The core command is jira issue search. Give it a --jql string and it returns matching issues. Start small with --limit so you can confirm the query is right before pulling a large result set:

# Ten most recently created issues in a project
atlassian-cli jira issue search \
  --jql "project = DEV ORDER BY created DESC" \
  --limit 10

The default output is a human-readable table, so this is genuinely usable as-is for a quick look. JQL clauses go in exactly as you would type them in the Jira issue navigator. Because JQL accepts single quotes for values, you can keep the outer shell quoting simple:

# Everything assigned to you that is still open
atlassian-cli jira issue search \
  --jql "assignee = currentUser() AND resolution = Unresolved ORDER BY updated DESC"

# In-progress work on one project, newest first
atlassian-cli jira issue search \
  --jql "project = DEV AND status = 'In Progress' ORDER BY updated DESC" \
  --limit 20

Any JQL that works in the Jira issue navigator works here unchanged, including functions such as currentUser(), openSprints(), and membersOf(), and relative dates like -7d or startOfWeek(). A practical habit is to draft a complex query in the web navigator first, confirm it returns what you expect, then copy the JQL string into a --jql flag. From that point on the query is portable: it drops into an alias, a script, or a scheduled job without any further editing.

If you manage more than one site, add --profile <name> to point the same query at a different instance. Profiles are configured once with auth login and stored in ~/.atlassian-cli/config.yaml; see the command reference for the full flag list. Every example on this page works against whichever profile is marked default, or the one you name explicitly.

Choose an output format

The reason the CLI beats copy-pasting from the web navigator is the --format flag (short form -f). The same JQL query can produce a table for reading, JSON for scripting, CSV for a spreadsheet, or markdown to paste into a ticket. Pick the format that matches what you are about to do with the data:

The markdown and quiet formats are easy to overlook but earn their place. Markdown output pastes cleanly into a pull request description, a Jira comment, or a Confluence page, which makes it handy for status updates built from a live query. The quiet format prints nothing and communicates only through the exit code, so a query can act as a gate: run it in CI, and let a non-empty result set fail the build.

Two extra flags matter when you script against JSON. The --output <file> flag writes results straight to a file instead of stdout, and --envelope wraps list output in {"data": [...], "count": N} so the row count travels with the data:

# Write results to a file instead of the terminal
atlassian-cli jira issue search \
  --jql "project = DEV AND type = Bug" \
  --format json --output bugs.json

# Wrap the array so you get {"data": [...], "count": N}
atlassian-cli jira issue search \
  --jql "project = DEV AND type = Bug" \
  --format json --envelope

Pipe JQL results to jq

JSON output is where the command line pulls ahead of the browser. Pipe the result into jq and you can reshape a JQL result set into exactly the fields you need, count things, or build a quick report without opening a spreadsheet.

# Just the issue keys
atlassian-cli jira issue search \
  --jql "project = DEV AND type = Bug" \
  --format json | jq '.[].key'

# Key and summary as tab-separated columns
atlassian-cli jira issue search \
  --jql "project = DEV AND status = 'In Progress'" \
  --format json | jq -r '.[] | [.key, .fields.summary] | @tsv'

# Count open bugs grouped by priority
atlassian-cli jira issue search \
  --jql "project = DEV AND type = Bug AND resolution = Unresolved" \
  --format json | jq 'group_by(.fields.priority.name)
    | map({priority: .[0].fields.priority.name, count: length})'

The pattern is always the same: let JQL do the filtering server-side, let the CLI hand you clean JSON, and let jq do the last-mile shaping. This composes with anything else in your shell. Pipe the keys into a while read loop to act on each issue, or into wc -l for a raw count. For deeper API-level work against Jira, the companion post on the Jira API from the command line goes further.

Export JQL results to CSV

For anyone who needs to hand data to a non-technical stakeholder, CSV is the answer. Combine --format csv with --output to produce a file that opens directly in Excel or Google Sheets:

# Export a filtered set to CSV
atlassian-cli jira issue search \
  --jql "project = DEV AND type = Bug AND created >= -30d" \
  --format csv --output recent-bugs.csv

jira issue search is ideal for interactive queries and moderate result sets. When you need to pull an entire project or a very large JQL result set, reach for jira bulk export instead. It handles pagination automatically and writes the complete result set to one file, in either JSON or CSV:

# Full export of a project, paginated automatically
atlassian-cli jira bulk export \
  --jql "project = DEV" \
  --output issues.json --format json

JSON exports preserve the full issue structure. CSV flattens the data into rows and columns for spreadsheet analysis. If your export feeds a recurring report, the Jira sprint report runbook shows how to wire a query into a scheduled, shareable summary.

Save the JQL queries you reuse

Here is the part that turns one-off commands into a real workflow. In the Jira web UI you would create a saved filter on the server. atlassian-cli runs JQL directly, so there is nothing to pre-create: the query is just text, and you save it wherever your shell can reach it. That means your "filters" live in version control alongside the rest of your tooling, not buried in a web menu.

Shell aliases for the queries you type constantly

Drop an alias in your ~/.zshrc or ~/.bashrc for the searches you run every morning:

# In ~/.zshrc or ~/.bashrc
alias my-open='atlassian-cli jira issue search --jql "assignee = currentUser() AND resolution = Unresolved ORDER BY updated DESC"'

alias sprint-bugs='atlassian-cli jira issue search --jql "project = DEV AND type = Bug AND sprint in openSprints()"'

Now my-open lists your open work and sprint-bugs shows the current sprint's bugs, no typing required.

Shell functions for queries that take a parameter

When a query changes by project or assignee, a small function beats a static alias:

# Open issues for any project you name: `open-in DEV`
open-in() {
  atlassian-cli jira issue search \
    --jql "project = $1 AND resolution = Unresolved ORDER BY updated DESC" \
    --limit 50
}

Scripts you can check into git

For anything more than a single line, keep the query in a script next to your team's other tooling. This one exports a weekly triage list to CSV and can be run on a schedule from cron:

#!/bin/bash
# triage-export.sh -- unassigned bugs from the last week, to CSV
set -euo pipefail

atlassian-cli jira issue search \
  --profile prod \
  --jql "project = DEV AND type = Bug AND assignee is EMPTY AND created >= -7d" \
  --format csv \
  --output "triage-$(date +%F).csv"

echo "Wrote triage-$(date +%F).csv"

Because the query text is plain and versioned, anyone on the team can read exactly what it matches, review changes in a pull request, and reuse it without hunting through Jira for the right saved filter. That reviewability is the practical advantage of keeping JQL in files rather than in the web UI.

How this differs from Atlassian's acli

atlassian-cli is an independent, community open-source project. It is not Atlassian's official CLI (acli) and is not affiliated with Atlassian. Use the official acli for first-party vendor support; use atlassian-cli if you want a single free binary spanning Jira, Confluence, Bitbucket, and JSM with the JQL, formatting, and export behaviour shown above. Both tools talk to the same Atlassian Cloud APIs, so the JQL you write is portable between them.

FAQ

Related Resources