Scry

A feature-rich, interactive Jira command-line interface built with TypeScript and Bun.

Scry is a powerful CLI tool for managing Jira from your terminal. Inspired by ankitpokhrel/jira-cli, it provides comprehensive support for Issues, Epics, Sprints, Projects, Boards, Releases, and Users, with multiple output formats including JSON and XML for seamless AI agent and scripting integration.

Features

• Full Jira Object Support: Issues, Epics, Sprints, Projects, Boards, Releases, Users
• Interactive & Scriptable: Rich terminal UI with prompts, plus non-interactive mode for automation
• Multiple Output Formats: table, plain, json, xml, csv - perfect for scripts and AI agents
• Powerful Filtering: JQL support, assignee/status/label filters, date ranges, custom queries
• Workflow Management: Create, edit, move, assign, comment, clone, and delete issues
• Fast & Modern: Built with Bun for blazing-fast startup and execution
• Simple Configuration: YAML config file + environment variables

Installation

Using Bun (Recommended)

bun install -g scry

Using npm

npm install -g scry

From Binary

Download the latest release for your platform from the releases page:

# macOS/Linux
curl -L https://github.com/sarlalian/scry/releases/latest/download/scry-[platform] -o scry
chmod +x scry
sudo mv scry /usr/local/bin/

From Source

git clone https://github.com/sarlalian/scry.git
cd scry
bun install
bun run build:local
# Binary will be in dist/scry

Quick Start

1. Initialize Configuration

scry init

This will guide you through setting up your Jira connection:

• Jira server URL (e.g., https://your-domain.atlassian.net)
• Email address
• Authentication type (Basic or Bearer)
• Default project (optional)

2. Set API Token

Generate an API token at Atlassian API Tokens, then:

export SCRY_API_TOKEN=your-token-here

Add this to your ~/.bashrc, ~/.zshrc, or equivalent for persistence.

3. Verify Connection

scry me

You should see your Jira user information!

Configuration

Config File

Scry searches for configuration in the following order:

1. Path specified by SCRY_CONFIG_FILE environment variable
2. .scry.yml in current directory
3. ~/.config/scry/config.yml (default)
4. ~/.scry.yml

Example ~/.config/scry/config.yml:

server: https://your-domain.atlassian.net
login: [email protected]
auth:
  type: basic  # or 'bearer'
project:
  key: PROJ
  type: classic  # or 'next-gen'
board:
  id: 123
  type: scrum  # or 'kanban'
output:
  format: table  # table|plain|json|xml|csv
  colors: true
issue:
  types:
    - name: Story
      handle: Story
    - name: Bug
      handle: Bug
    - name: Task
      handle: Task

Environment Variables

Override config values with environment variables:

export SCRY_API_TOKEN=your-token           # Required
export SCRY_SERVER=https://domain.atlassian.net
export [email protected]
export SCRY_PROJECT=PROJ
export SCRY_AUTH_TYPE=basic                # basic or bearer
export SCRY_CONFIG_FILE=/path/to/config.yml

Global Options

All commands support these global options:

-c, --config <path>      # Custom config file path
-p, --project <key>      # Override project key
-o, --output <format>    # Output format: table|plain|json|xml|csv
--no-color              # Disable colored output
--debug                 # Enable debug logging

Commands

Issue Management

List Issues

# List all issues in default project
scry issue list

# Filter by assignee
scry issue list -a [email protected]
scry issue list -a x  # Unassigned issues

# Filter by status
scry issue list -s "In Progress"
scry issue list -s "~Done"  # Exclude Done status

# Filter by type, priority, labels
scry issue list -t Bug -y High -l urgent -l security

# Date filters
scry issue list --created -7d     # Created in last 7 days
scry issue list --updated week    # Updated this week
scry issue list --created month   # Created this month

# Raw JQL query
scry issue list -q "assignee = currentUser() AND sprint in openSprints()"

# Watching issues
scry issue list -w

# Sort and limit
scry issue list --order-by updated --reverse --limit 10

# Custom columns
scry issue list --columns key,summary,status,assignee

# JSON output for scripting
scry issue list -o json --limit 50

View Issue

# View issue details
scry issue view PROJ-123

# Different output formats
scry issue view PROJ-123 -o json
scry issue view PROJ-123 -o xml

Create Issue

# Interactive mode (prompts for all fields)
scry issue create

# With flags (still prompts for missing required fields)
scry issue create -p PROJ -t Story -s "Add user authentication"

# Fully non-interactive
scry issue create \
  -p PROJ \
  -t Task \
  -s "Implement feature X" \
  -d "Detailed description here" \
  -a [email protected] \
  -y High \
  -l backend -l api

# Create subtask
scry issue create -p PROJ -t Sub-task -P PROJ-123 -s "Subtask title"

# Force interactive even with flags
scry issue create -t Story -i

Edit Issue

# Interactive mode
scry issue edit PROJ-123

# Update specific fields
scry issue edit PROJ-123 -s "Updated summary"
scry issue edit PROJ-123 -d "New description" -y Medium
scry issue edit PROJ-123 -l new-label -C ComponentName

Move Issue (Transitions)

# Interactive mode (shows available transitions)
scry issue move PROJ-123

# Direct transition
scry issue move PROJ-123 "In Progress"
scry issue move PROJ-123 Done

Assign Issue

# Assign to user
scry issue assign PROJ-123 [email protected]

# Unassign
scry issue assign PROJ-123 x

Comment on Issue

# Add comment interactively
scry issue comment add PROJ-123

# Add comment directly
scry issue comment add PROJ-123 "This is a comment"

# Use editor for longer comments
scry issue comment add PROJ-123 -e

# From flag
scry issue comment add PROJ-123 -b "Comment text here"

Clone Issue

# Clone issue interactively
scry issue clone PROJ-123

# Clone with new summary
scry issue clone PROJ-123 -s "Cloned: Original Title"

# Clone to different project
scry issue clone PROJ-123 -p NEWPROJ

Delete Issue

# Delete single issue
scry issue delete PROJ-123

# Delete multiple issues
scry issue delete PROJ-123 PROJ-124 PROJ-125

# Skip confirmation
scry issue delete PROJ-123 -y

Epic Management

List Epics

# List all epics in default project
scry epic list

# Filter and format
scry epic list -p PROJ -o json

Create Epic

# Interactive mode
scry epic create

# With flags
scry epic create -p PROJ -s "Epic Name" -d "Epic description"

Add Issues to Epic

scry epic add EPIC-1 PROJ-123 PROJ-124 PROJ-125

Remove Issues from Epic

scry epic remove EPIC-1 PROJ-123 PROJ-124

Sprint Management

List Sprints

# List sprints from default board
scry sprint list

# List from specific board
scry sprint list -b 123

# Filter by state
scry sprint list --state active
scry sprint list --state future
scry sprint list --state closed

Create Sprint

# Interactive mode
scry sprint create

# With flags
scry sprint create -b 123 -n "Sprint 42" -g "Sprint 42 Goals"

Add Issues to Sprint

scry sprint add 456 PROJ-123 PROJ-124 PROJ-125

Project Management

# List all projects
scry project list

# JSON output
scry project list -o json

Board Management

# List all boards
scry board list

# Filter by type
scry board list -t scrum
scry board list -t kanban

# JSON output
scry board list -o json

Release/Version Management

# List releases for default project
scry release list

# List for specific project
scry release list PROJ

# Create release
scry release create

# With flags
scry release create -p PROJ -n "v1.0.0" -d "Release description"

User Management

# Search for users
scry user search john

# Limit results
scry user search john --limit 10

# JSON output
scry user search john -o json

Utility Commands

Get Current User

scry me

Open in Browser

# Open issue in browser
scry open PROJ-123

# Open project
scry open PROJ

# Open board
scry open -b 123

# Open sprint in board
scry open -b 123 -s 456

Output Formats

All commands support the -o, --output flag with the following formats:

Table (Default)

Rich, colored terminal output with tables:

scry issue list

Plain

Simple text output without colors:

scry issue list -o plain

JSON

Structured JSON for scripting and AI agents:

scry issue list -o json

JSON output structure:

{
  "data": [...],
  "meta": {
    "total": 100,
    "maxResults": 50,
    "startAt": 0
  }
}

XML

XML format for legacy integrations:

scry issue list -o xml

CSV

Comma-separated values for spreadsheets:

scry issue list -o csv > issues.csv

Advanced Usage

JQL Queries

Use raw JQL for complex queries:

# Find my open bugs
scry issue list -q "assignee = currentUser() AND type = Bug AND status != Done"

# Issues updated in last 2 weeks
scry issue list -q "updated >= -2w ORDER BY updated DESC"

# Complex sprint query
scry issue list -q "project = PROJ AND sprint in openSprints() AND status = 'In Progress'"

Scripting with JSON Output

#!/bin/bash

# Get all open issues and extract keys
issues=$(scry issue list -s "~Done" -o json | jq -r '.data[].key')

# Process each issue
for issue in $issues; do
  echo "Processing $issue"
  # Do something with each issue
done

CI/CD Integration

# GitHub Actions example
name: Check Jira Issues
on: [push]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: Setup Bun
        uses: oven-sh/setup-bun@v1

      - name: Install Scry
        run: bun install -g scry

      - name: Check Issues
        env:
          SCRY_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
          SCRY_SERVER: https://your-domain.atlassian.net
          SCRY_LOGIN: [email protected]
        run: |
          scry issue list -o json > issues.json
          # Process issues.json

AI Agent Integration

Scry's JSON/XML output makes it perfect for AI coding agents:

import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

async function getJiraIssues() {
  const { stdout } = await execAsync('scry issue list -o json --limit 100');
  const result = JSON.parse(stdout);
  return result.data;
}

async function createIssueFromAI(summary, description) {
  await execAsync(
    `scry issue create -p PROJ -t Task -s "${summary}" -d "${description}"`
  );
}

Multiple Jira Instances

Use different config files for different instances:

# Work Jira
export SCRY_CONFIG_FILE=~/.config/scry/work.yml
scry issue list

# Personal Jira
export SCRY_CONFIG_FILE=~/.config/scry/personal.yml
scry issue list

Or use command-line config override:

scry -c ~/.config/scry/work.yml issue list
scry -c ~/.config/scry/personal.yml me

Development

Prerequisites

• Bun >= 1.1.0

Setup

git clone https://github.com/sarlalian/scry.git
cd scry
bun install

Development Commands

bun run dev                # Run in development mode
bun run src/index.ts       # Run CLI directly
bun --hot src/index.ts     # Hot reload during development
bun test                   # Run tests
bun test --watch           # Watch mode
bun test --coverage        # With coverage
bun run lint               # Lint code
bun run typecheck          # Type checking
bun run build:local        # Build local binary
bun run build              # Build all platform binaries

Project Structure

scry/
├── src/
│   ├── index.ts           # Entry point
│   ├── cli/               # CLI commands and middleware
│   │   ├── commands/      # Command implementations
│   │   └── middleware/    # Auth, config, output handlers
│   ├── api/               # Jira API client
│   │   ├── client.ts      # HTTP client
│   │   ├── auth/          # Authentication providers
│   │   ├── endpoints/     # API endpoint modules
│   │   └── types/         # TypeScript types
│   ├── config/            # Configuration management
│   ├── output/            # Output formatters
│   ├── tui/               # Terminal UI components
│   └── utils/             # Utilities
├── tests/                 # Test files
└── docs/                  # Documentation

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository and create a feature branch
2. Write tests for new features
3. Follow the code style (enforced by ESLint)
4. Update documentation for user-facing changes
5. Test thoroughly with bun test
6. Submit a pull request with a clear description

Development Guidelines

• Use TypeScript for all new code
• Prefer Bun APIs over Node.js equivalents where possible
• Write unit tests for new functionality
• Follow existing patterns for commands and output formatting
• Keep commits atomic and well-described

Technology Stack

| Component | Technology | |-----------|------------| | Runtime | Bun | | Language | TypeScript 5.x | | CLI Framework | Commander.js | | Prompts | @inquirer/prompts | | HTTP Client | Native fetch | | Configuration | YAML | | Output | chalk, cli-table3, fast-xml-parser | | Testing | Bun test | | Build | Bun compile |

License

MIT License - see LICENSE file for details.

Acknowledgments

• Inspired by ankitpokhrel/jira-cli
• Built with Bun - a fast all-in-one JavaScript runtime
• Uses the Jira REST API

Support

• Issues: GitHub Issues
• Documentation: This README and CLAUDE.md
• Discussions: GitHub Discussions

Made with TypeScript and Bun