@knpkv/jira-cli

CLI tool to fetch Jira tickets and export to markdown.

Installation

pnpm add @knpkv/jira-cli

Or link globally for development:

cd packages/jira-cli && pnpm link --global

Setup

1. Create OAuth App

jira auth create

Opens Atlassian Developer Console. Create a new OAuth 2.0 (3LO) app with:

Permissions:

• Jira API: read:jira-work, read:jira-user
• User Identity API: read:me

Callback URL:

http://localhost:8585/callback

2. Configure Credentials

jira auth configure --client-id <ID> --client-secret <SECRET>

3. Login

jira auth login

Usage

Search by JQL

jira search 'project = PROJ AND status = Done'

Search by Fix Version

jira search --by-version "1.0.0"
jira search --by-version "1.0.0" --project PROJ

Options

| Option | Alias | Description | Default | | --------------- | ----- | ---------------------------------------- | ---------------- | | --by-version | -v | Search by fix version | - | | --project | -p | Filter by project key | - | | --output-dir | -o | Output directory | ./jira-tickets | | --format | -f | multi (one file per issue) or single | multi | | --max-results | -m | Max results to fetch | 100 |

Output Formats

Multi (default): One markdown file per issue with YAML front-matter.

./jira-tickets/
├── PROJ-123.md
├── PROJ-124.md
└── PROJ-125.md

Single: All issues in one combined file.

./jira-tickets/
└── jira-export.md

Auth Commands

jira auth create     # Open Atlassian console to create OAuth app
jira auth configure  # Set client ID and secret
jira auth login      # Authenticate via OAuth
jira auth logout     # Remove stored credentials
jira auth status     # Show current auth status

Programmatic Usage

import { Effect, Layer } from "effect"
import * as Redacted from "effect/Redacted"
import { IssueService, IssueServiceLayer } from "@knpkv/jira-cli"
import { JiraApiClient, JiraApiConfig, toEffect } from "@knpkv/jira-api-client"

const configLayer = Layer.succeed(JiraApiConfig, {
  baseUrl: "https://mysite.atlassian.net",
  auth: {
    type: "basic",
    email: "[email protected]",
    apiToken: Redacted.make("your-api-token")
  }
})

// Using IssueService (high-level)
const program = Effect.gen(function* () {
  const service = yield* IssueService
  const issues = yield* service.searchAll('fixVersion = "1.0.0"')
  console.log(`Found ${issues.length} issues`)
}).pipe(Effect.provide(IssueServiceLayer), Effect.provide(JiraApiClient.layer), Effect.provide(configLayer))

// Or using JiraApiClient directly (low-level)
const direct = Effect.gen(function* () {
  const client = yield* JiraApiClient
  const issue = yield* toEffect(
    client.v3.client.GET("/rest/api/3/issue/{issueIdOrKey}", {
      params: { path: { issueIdOrKey: "PROJ-123" } }
    })
  )
  console.log(issue.fields?.summary)
}).pipe(Effect.provide(JiraApiClient.layer), Effect.provide(configLayer))

License

MIT