Hand Jira to your agents.

A Jira Cloud CLI that AI agents can drive: planning sprints, writing standup digests and updating tickets as code merges.

Set up your agent

Independently maintained. Not affiliated with Atlassian.

View on GitHub

Open source under the AGPL-3.0 license.

Runs within your Jira permissions, using your existing API token.

Install

curl -fsSL https://raw.githubusercontent.com/User17745/jira-cli-toolkit/main/scripts/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"

macOS 15 or later, on Apple Silicon or Intel. The installer verifies release checksums first.

curl -fsSL https://raw.githubusercontent.com/User17745/jira-cli-toolkit/main/scripts/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"

x86_64 with glibc 2.39 or later, such as Ubuntu 24.04. The installer verifies release checksums first.

irm https://raw.githubusercontent.com/User17745/jira-cli-toolkit/main/scripts/install.ps1 | iex

Windows 10 or later on x86_64, with PowerShell 5.1 or later. The installer verifies release checksums first.

Prefer a manual install?Upgrading from jsup?

Works with any agent that can run a shell command, including

Claude Code
Pi
OpenCode
Command Code
Cursor
GitHub Copilot
Gemini CLI
Cline
Windsurf
Zed
Warp
Qwen Code

Days of sprint planning, done in hours

This toolkit started as its maintainer’s own Jira setup. The job was a full roadmap, broken into weekly sprints, with business, product, backend, frontend and QA working in parallel. Everyone had to be close to fully booked, with time held back for ad-hoc work.

Every change meant checking capacity, blockers and parallel streams again, by hand. That’s days of work. With a CLI the agent could read and write, the plan became code. The agent drafted the sprints, wrote a test for every rule, and kept re-planning until all of them passed. Only then did it write to Jira.

roadmapstreams, owners, estimates
draft sprintsplan.yaml
run the checkscapacity ≤ 80%
dependencies land first
streams in parallel
write to Jiraonce, after ✓

Time to a checked plan: days → hours
Streams planned together: 5
Jira issues created from the plan: 87

The replay plans a sample project, not the original roadmap.

What agents do with it

Pick a card to watch it in the sandbox terminal. Each replay is a coding-agent session in the sandbox: your request in plain words, the jira commands the agent runs against the sample site, and its answer. Writes stay in the sandbox, so you can inspect them afterwards.

You ask your agent

Plan the checkout launch (APP) into weekly sprints on board 18. Keep everyone at or under 80% so there’s room for ad-hoc work, run the streams in parallel, and don’t schedule anything before what it depends on lands. Test the plan before you touch Jira.

Reads the backlog as JSON, with owners and estimates.
Writes the plan to a file, with tests for capacity, dependencies and parallel streams.
Re-plans until every test passes, then creates the sprints and fills them.

Commands it uses

issue list --json --fields
sprint create
sprint add-issues
sprint list

Set up your agent once

Any agent that can run a shell command can use jira. Sign in once yourself, then give the agent the rules below.

Install the CLI and sign in. On macOS, run jira auth status once and choose Always Allow, so later runs without a terminal can read the keychain. Setup for each system.
jira auth login --profile work

Teach your agent the rules. A skill loads by itself in every session; AGENTS.md covers one repository.

Paste this prompt into your agent once. It writes a skill that triggers whenever a task involves Jira, so later sessions use jira without being told.

Create a skill named "jira" so that every future session uses the jira CLI for Jira work, without my asking.

- Save it where you load skills or global rules in every session, not only in this repository. For Claude Code, that's ~/.claude/skills/jira/SKILL.md. If you don't support skills, add it to your global rules file instead.
- Write its description so it triggers on any Jira work: issues, sprints, boards, backlogs, standups, release notes, and updating tickets after commits or merges.
- In the body, include the rules below and a short summary of `jira --help`.
- When you're done, show me the file and tell me how to check that it loads.

## Jira
- Before the first Jira task, run `jira auth status --json --no-input`. If it fails, stop and ask me to sign in from my own terminal: `jira auth login --profile work`, then on macOS `jira auth status --profile work` once, choosing Always Allow. Never ask for my API token or try to sign in yourself.
- Use the `jira` CLI for all Jira work. Run `jira help <command>` before using a command for the first time.
- Add `--json --no-input` to every command and read results from stdout. Errors are JSON too: exit 1 means Jira refused, exit 2 means fix the command.
- Look before you write: `jira project fields <KEY> --type <type>` lists required fields, and `jira issue transitions <KEY>` lists valid moves.
- For changes to many issues, write the plan to a file and test it first. Write to Jira only after the checks pass.
- Never delete issues, comments, links or attachments unless I ask. Deletes need `--yes`.
- If no command covers it, look the endpoint up with `jira api <path> --spec` before calling `jira api`.

Ask for the work in plain words, as in the use cases above. If the CLI isn’t signed in yet, the rules make the agent stop and walk you through it instead of guessing. Replay a first run to see what it says.

Your agent acts as you, with every permission your Jira account has. To limit it, give it its own account and profile, or a scoped token. What the profile does and doesn’t protect.

Try it yourself

The sandbox terminal runs on sample data from an example site. Nothing reaches Jira. Pick a command, or type your own.

Built for agents and scripts to drive

Agents can’t watch a spinner or answer a prompt. Data goes to stdout, messages and prompts to stderr. Add --json and failures become JSON on stdout too, so nothing has to parse prose.

Exit	Meaning	Example
0	Success. Data is on stdout. Example: `jira issue list --open --json --limit 1` returns one open issue as JSON, so it exits 0.
1	Jira or network error. Jira refused the request, or couldn’t be reached. Example: `jira issue view ENG-99` asks for an issue that doesn’t exist, so Jira answers 404, so it exits 1.
2	Invalid input. Bad arguments, missing values or configuration. Example: `jira issue list --json --csv` combines two output formats that can’t be used together, so it exits 2.
130	Interrupted. Ctrl+C stopped the command, or input ended at a prompt. Press `Ctrl` `C` in the terminal to see it.

Every error has one shape with `--json`

$ jira issue view ENG-99 --json
{
  "error": {
    "code": "jira_error",
    "message": "Error: GET /rest/api/3/issue/…",
    "status": 404
  }
}

--no-input, or any input that isn’t a terminal, never prompts. Missing values fail with exit 2.
Global flags such as --project and --json work before or after the command.
Deletes ask for confirmation, or need --yes when nothing can prompt.
Tokens stay in your OS credential store and are redacted from error output.

Every command, read from the parser

This list is generated from the argument parser in jira 2.5.2, so it can’t drift from the tool. Select a command to open its real help in the terminal.

61 commands

jira issue

jira board

jira sprint

jira config

jira project

jira template

jira auth

jira profile

jira context

jira component

jira user

setup and maintenance

From install to your first list

Choose your system and run its install command. It puts jira on your PATH.
Sign in with an API token. Guided login links to token creation, explains scopes, and stores the token in your OS credential store by default. For headless use, choose environment authentication or explicit POSIX plaintext file storage. Each profile is one account, so sign in again with another name to add a second, and switch with jira profile use.
jira auth login --profile work
Pick a default project, then list what’s open.
jira context use --project ENGjira issue list --open

Before you install

What it supports today, and what it doesn’t yet.