Getting Started with Jira on 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.

What You Need First

To use Jira from the command line, install a CLI tool, generate an Atlassian API token, log in once, then run commands like atlassian-cli jira issue search and atlassian-cli jira issue create. This guide walks a first-time user through every step, from a blank terminal to searching, creating, and transitioning issues without ever opening a browser tab.

The Jira web UI is fine for reading one ticket at a time, but it gets slow when you want to script things: pulling a list of open bugs into a spreadsheet, creating ten tickets from a checklist, or moving a batch of issues to Done at the end of a sprint. A command line workflow turns those chores into a single repeatable line you can save, share, or drop into a shell script.

Before you start, make sure you have three things:

• A terminal. Terminal on macOS, any shell on Linux, or PowerShell / Windows Terminal on Windows.
• A Jira Cloud account on an *.atlassian.net site, with the email you sign in with.
• Permission to create an API token. Any standard Atlassian account can do this; you do not need to be a site admin.

Step 1: Install the CLI

atlassian-cli is a single self-contained binary, so installation is fast. Pick whichever method matches your setup.

On macOS or Linux, Homebrew is the simplest path and keeps the tool updated with brew upgrade:

# macOS / Linux via Homebrew
brew install omar16100/atlassian-cli/atlassian-cli

If you already have the Rust toolchain, you can build from source with Cargo instead:

# Any platform with Rust 1.75+
cargo install atlassian-cli

Prefer no build step at all? Download a prebuilt binary for macOS, Linux, or Windows from the GitHub releases page and drop it anywhere on your $PATH. Full details for every method are on the install page.

Whatever method you chose, confirm it worked:

atlassian-cli --version
atlassian-cli --help

You should see a version number and the top-level help listing the command groups: jira, confluence, bitbucket, jsm, and auth. If you get command not found, the install directory is not on your $PATH yet. For Homebrew on Apple Silicon that directory is /opt/homebrew/bin.

Step 2: Create an API Token

Jira Cloud does not accept your account password over the API, so the CLI authenticates with an API token instead. Creating one takes about thirty seconds:

1. Go to id.atlassian.com/manage-profile/security/api-tokens.
2. Click Create API token, give it a label like atlassian-cli, and copy the value.
3. Store it somewhere safe. You can only view the token once.

The token authenticates as you. Anything your account can do in the Jira web UI, the CLI can do with that token, and nothing more. It is not an admin-only feature and it does not grant extra access.

A good habit is to keep the token in a shell variable so it never lands in your shell history or in a saved command:

# Paste your token once, per shell session
export ATLASSIAN_API_TOKEN="your-token-value-here"

Step 3: Log In

Now connect the CLI to your Jira site with auth login. A profile is just a local name for one account, so you can keep several (for example a personal sandbox and a work instance) and switch between them later.

atlassian-cli auth login \
  --profile work \
  --base-url https://your-domain.atlassian.net \
  --email you@company.com \
  --token $ATLASSIAN_API_TOKEN \
  --default

Each flag is straightforward:

• --profile is a local nickname for this account, anything you like.
• --base-url is your Atlassian Cloud URL, including https:// and no trailing slash.
• --email is the account that owns the token.
• --token is the API token from Step 2.
• --default makes this the profile used whenever you omit --profile.

Credentials are written to disk encrypted with AES-256-GCM and stay on your machine. Confirm the login works before going further:

atlassian-cli auth test --profile work
atlassian-cli auth whoami --profile work

If auth test returns a success and whoami prints your account, you are connected. A 401 Unauthorized almost always means the token or email is wrong; regenerate the token and try again. For CI pipelines, multiple profiles, and Bitbucket tokens, see the full authentication guide.

Step 4: Your First Commands

You are ready to work. Every Jira command follows the same shape: atlassian-cli jira issue <verb>. Here are the ones you will reach for on day one.

Search for issues

Search uses JQL, the same query language as the Jira UI. Start small and add a --limit so you do not fetch your whole backlog:

# The 5 most recently created issues in project DEV
atlassian-cli jira issue search \
  --jql "project = DEV order by created desc" \
  --limit 5

If you are new to JQL, the JQL query cheat sheet collects the filters you will use most: by status, assignee, sprint, label, and date.

Read one issue

atlassian-cli jira issue get DEV-123

Create an issue

You need a project key, an issue type, and a summary. That is the minimum to file a ticket:

atlassian-cli jira issue create \
  --project DEV \
  --issue-type Task \
  --summary "Write onboarding docs"

Update, transition, and assign

Once an issue exists, you edit it by key. These three cover most of what you do in a ticket's lifetime:

# Change the summary
atlassian-cli jira issue update DEV-123 --summary "Updated summary"

# Move it through the workflow
atlassian-cli jira issue transition DEV-123 --transition "In Progress"

# Assign it to a teammate
atlassian-cli jira issue assign DEV-123 --assignee teammate@company.com

You can also list projects to find the right key, which is handy on a site you do not know well:

atlassian-cli jira project list

Here is the full beginner toolkit in one place:

Reading and Reusing Output

By default commands print a human-readable table. The moment you want to feed Jira data into another tool, switch the format with --format (or -f). Supported values are table, json, csv, yaml, markdown, and quiet.

# JSON, then pull out just the issue keys with jq
atlassian-cli jira issue search \
  --jql "project = DEV AND status = 'To Do'" \
  --format json | jq '.[].key'

# CSV straight into a file for a spreadsheet
atlassian-cli jira issue search \
  --jql "project = DEV AND type = Bug" \
  --format csv --output bugs.csv

This is where the command line starts to pay off. The same query that showed you a table on screen can, with one extra flag, become a CSV for a stakeholder or a JSON stream piped into a script. If you want to go deeper on scripting the REST API through the CLI, the Jira API from the command line guide picks up where this one ends.

Every command also accepts --profile <name> to target a specific account, so once you have more than one profile you can run the same search against work and personal sites without logging out:

atlassian-cli jira issue search --profile personal --jql "project = PERS"
atlassian-cli jira issue search --profile work --jql "project = DEV"

How This Differs from acli

Atlassian maintains its own official CLI called acli. atlassian-cli is a separate, independent, community open-source project and is not affiliated with, endorsed by, or maintained by Atlassian. Both let you drive Jira from a terminal, but they are different tools with different goals.

• Choose the official acli when you want a first-party, vendor-supported tool backed directly by Atlassian.
• Choose atlassian-cli when you want a single free Rust binary that spans Jira, Confluence, Bitbucket, and Jira Service Management, with one auth setup shared across all four.

Neither choice locks you in. They read the same Atlassian Cloud, so you can try both and keep whichever fits your workflow. Everything in this guide uses atlassian-cli, and every command above is verified against the command reference.

From here, the natural next steps are learning JQL well enough to filter precisely, and batching changes across many issues at once. The Jira CLI reference is the map for both.

FAQ

Related Resources