jira-cli: working with Jira Server from the terminal

With jira-cli, I can read an issue and check its status from the terminal, then add a comment or screenshot when needed. The same commands return JSON for a script or coding agent, and changes are previewed before they are sent.

I built it for self-hosted Jira Server 7.x and REST API v2. It is an independent open-source project, not an official Atlassian tool.

Commands for daily ticket work

Use mine to find your issues, show to read one, and comment to prepare a reply. Each command calls Jira directly and exits, so an agent can invoke it without starting an MCP server.

Changes default to dry runs. Check the target issue and proposed text, then add the action flag to send the change. This gives you a chance to review both manual commands and automated updates.

The tool interface also supports board queries, work logs, attachments, and issue links without requiring you to call the API endpoints yourself.

Install and connect

You need Node.js 18.17 or newer and an account on the Jira Server instance.

npm install -g @khanglvm/jira-cli

Set JIRA_USERNAME and JIRA_PASSWORD in your local environment. Replace the example address with your Jira URL:

jira-cli profile add work \
  --base-url https://jira.example.com \
  --username "$JIRA_USERNAME" \
  --password "$JIRA_PASSWORD" \
  --default

Credentials go into the OS keychain by default. Keep them out of source files and chat messages. To use multiple accounts or workspaces on one machine, create named profiles. Check them with jira-cli profile list and select one with jira-cli profile use work.

Read a ticket, then preview a comment

Start with your unresolved issues:

jira-cli mine --max-results 10

Copy an issue key from that result and replace PROJ-123 below:

jira-cli show PROJ-123
jira-cli comment PROJ-123 --body "Investigating the login issue."

The comment command above previews the action. To post it after checking the issue and text, add --perform-action:

jira-cli comment PROJ-123 \
  --body "Investigating the login issue." \
  --perform-action

To include evidence with the explanation, use --inline-image screenshot.png to upload and embed an image in the comment, or --attach notes.txt to add a file such as a log.

Search is available through JQL or common filters. For example:

jira-cli search --reported --order-by "priority DESC"

Using it with a coding agent

You can pass this instruction to your coding assistant:

Use jira-cli for this Jira task. Check existing profiles, then read the issue.
Run `jira-cli easy` if you need command examples. Preview the proposed change
before executing it. Use --perform-action only for changes I asked for,
and report the issue key and what changed.

An optional skill contains the command workflow and setup guidance:

npx skills add khanglvm/jira-cli --skill jira-cli -y

Account for the project’s workflow

Check a project’s available transitions before moving an issue. Projects can use different workflows, and an issue type such as “Bug” is separate from a status such as “In Progress.” The configured account still needs permission to make the change.

The usage guide covers transitions and user assignment, with a full tool list. The package is on npm. Run jira-cli --help to see the available commands.