jira-cli

oasis-jira — an AXI-compliant CLI for the Oasis Jira server. Search issues with JQL, read details and comments, create/update/transition issues, log time, and manage attachments — with token-efficient TOON output built for autonomous agents.

Extracted from the oasis-core Claude Code plugin so it can be installed, versioned, and released on its own.

Quick Start

Install the jira-cli skill in the Agent Skills format with npx skills:

npx skills add oasissys/jira-cli --skill jira-cli -g

That is the entire setup — the skill teaches your agent the CLI, and it runs without a global install as npx -y @oasissys/jira-cli (Node 20+ required). Installing the skill itself needs GitHub access to this private repo.

-g installs the skill for all projects (~/.claude/skills/); drop it to install for the current project only.

Other ways to install

Zero setup

Any capable agent can run the CLI directly with nothing installed. Just tell your agent:

Execute `npx -y @oasissys/jira-cli` to get Oasis Jira tools.

Global install + session hook

Want the CLI on PATH and your open Jira issues fed into every agent session?

npm install -g @oasissys/jira-cli   # installs `oasis-jira` (and the `jira-cli` alias)
oasis-jira setup

setup registers a SessionStart hook for Claude Code, Codex, and OpenCode that surfaces your open Jira issues at session start — restart your agent session after running it. If you use the oasis-core Claude Code plugin, it already ships this hook; skip setup or remove one of the two.

From a clone (development)

pnpm install && pnpm run build && pnpm link --global

Authenticate

Credentials live in ~/.oasis.json (shared with the other oasis CLIs and the Oasis dashboard) and are verified against the live server before being saved.

oasis-jira auth --user <username> --password <password>
oasis-jira auth            # show current status
oasis-jira auth --clear    # sign out

Use

oasis-jira                                            # live view: your unresolved issues
oasis-jira search "project = SOF AND status = Open"   # any JQL query
oasis-jira issue SOF-42                               # full details + recent comments
oasis-jira epic SOF-10                                # an epic's child issues
oasis-jira transitions SOF-42                         # available status transitions
oasis-jira transition SOF-42 Done                     # change status
oasis-jira comment SOF-42 --body "Fixed"              # add a comment
oasis-jira worklogs SOF-42                            # list worklog entries
oasis-jira timesheet --month 2026-06                  # monthly worklogs per day/issue
oasis-jira attachments SOF-42                         # list attachments
oasis-jira attachment SOF-42 10123 --out spec.pdf     # download an attachment
oasis-jira create SOF --type Bug --summary "Login fails"
oasis-jira update SOF-42 --field duedate=2026-08-01
oasis-jira add-worklog SOF-42 --time "1h 30m"

Every command supports --help. Output is TOON on stdout, diagnostics on stderr, exit codes 0/1/2 (success/error/usage).

Development

pnpm run dev -- search "assignee = currentUser()"   # run from source
pnpm test                                            # vitest
pnpm run lint                                        # eslint
pnpm run build:skill                                 # regenerate SKILL.md

Releases are cut by release-please from conventional commits on main. Do not hand-edit CHANGELOG.md, .release-please-manifest.json, or skills/jira-cli/SKILL.md — they are generated.