Skip to content

README.md

Latest commit

 

History

History
227 lines (163 loc) · 7.83 KB

README.md

File metadata and controls

227 lines (163 loc) · 7.83 KB


An AI backed CLI tool for analyzing JIRA data

Issues Open PRs Forks Stars License CI Status

jiaz

jiaz is a command-line software designed for analyzing JIRA data with speed and flexibility. Whether you are a developer, project manager, or data analyst, JIAZ empowers you to extract insights, automate reporting, and streamline your workflow with minimal setup.

jiaz helps streamline JIRA hygiene by automating routine tasks—such as grooming story descriptions or validating epic summaries—turning hours of manual effort into just minutes.

🤖 AI-Powered Analysis

jiaz integrates with both local Ollama models and Google's Gemini for intelligent JIRA data analysis with an automatic fallback to Ollama if Gemini isn’t configured.

  • ☁️ Cloud Power: Leverages Google's Gemini for faster, more capable analysis if key is configured.
  • 🏠 Local Processing: Uses Ollama for privacy-focused, offline analysis.

🚀 Installation Methods

You can install and use jiaz in two ways:

📦 1. Using Prebuilt Binaries (Recommended for End Users)

  • ✅ Steps:

    1. Go to GitHub Actions tab of this repo.
    2. Find the latest successful CI workflow run for the main branch.
    3. Click on the workflow run.
    4. Check the Artifacts tab.
    5. Download the zip file for your OS:
    • jiaz-macos-latest.zip (macOS)
    • jiaz-linux-latest.zip (Linux)
    • jiaz-windows-latest.zip (Windows)

    1. After downloading the appropriate zip file for your OS, follow these platform-specific steps:

      • 🍎 macOS Installation:

        • Extract directly to /opt/jiaz (adjust download path as needed)

          sudo unzip ~/Downloads/jiaz-macos-latest.zip -d /opt/jiaz

        • Make executable

          sudo chmod +x /opt/jiaz/jiaz

        • Remove macOS quarantine attribute

          sudo xattr -dr com.apple.quarantine /opt/jiaz

          Note : To re-apply quarantine, run xattr -w com.apple.quarantine "0002;..." /opt/jiaz

        • Add to PATH (temporary)

          export PATH="/opt/jiaz:$PATH"

        • Add to PATH (permanent) for zsh (default on macOS Catalina+)

          echo 'export PATH="/opt/jiaz:$PATH"' >> ~/.zshrc

        • Verify installation

          jiaz --help
      • 🐧 Linux Installation:

        • Extract directly to /opt/jiaz (adjust download path as needed)

          sudo unzip ~/Downloads/jiaz-linux-latest.zip -d /opt/jiaz

        • Make executable

          sudo chmod +x /opt/jiaz/jiaz

        • Add to PATH (temporary)

          export PATH="/opt/jiaz:$PATH"

        • Add to PATH (permanent) for bash

          echo 'export PATH="/opt/jiaz:$PATH"' >> ~/.bashrc

        • Verify installation

          jiaz --help
      • 🪟 Windows Installation:

        • Using PowerShell (Run as Administrator):

          • Extract to Program Files (adjust download path as needed)

            Expand-Archive -Path "$env:USERPROFILE\Downloads\jiaz-windows-latest.zip" -DestinationPath "C:\Program Files\jiaz"

          • Add to PATH permanently

            $env:PATH += ";C:\Program Files\jiaz"
[Environment]::SetEnvironmentVariable("PATH", $env:PATH, [EnvironmentVariableTarget]::Machine)

          • Verify installation (open new PowerShell/CMD)

            jiaz --help

        • Using UI:

          • Extract using built-in tools or 7-zip at C:\Program Files\jiaz

          • Then go to PATH via System Properties > Environment Variables

          • Add C:\Program Files\jiaz to the PATH variable

          • Verify installation (open new CMD)

          jiaz --help

📝 Note: Download paths may vary depending on your browser settings. Adjust the paths in the commands above to match your actual download location.

🧑‍💻 2. Build Binary locally using pip and pyinstaller

  • ✅ Prerequisites:
    • Python 3.8+
    • pyenv (recommended)
    • make
  • ✅ Steps:
    • Fork the repository from upstream
    • Clone the forked repository 
      git clone <url_for_your_fork>
    • Change directory 
      cd </path/to/jiaz>
    • [Optional] Create a virtual env with Python >= 3.10 and activate it.
    • Run the make target to build 
      make build

      If you do not have make installed, check on the commands for the target in the makefile for build

After running make build, jiaz directory will be created in dist/ folder. You can either run the jiaz binary from within jiaz folder or have it setup system-wide. To install it system-wide, proceed with the OS specific installation steps provided above.

🧹 Cleaning Up

make clean  # Removes build/dist folders, pycache, and spec files

🧪 Usage

  • 📋 Configuration Management

    Note : For jiaz to be able to extract data from JIRA, config setup is must.

    • Use jiaz config init command to create first block of configuration.

      jiaz config [SUBCOMMAND] [OPTIONS]

    • 📖 Visit here, for detailed configuration documentation.

  • 📊 Data Analysis

    • Use jiaz analyze commands to analyze JIRA data with AI-powered features.

      jiaz analyze [SUBCOMMAND] [OPTIONS]

    • 📖 Visit here, for detailed configuration documentation.

💡 Tip: Use --help with any command to see detailed usage information

🔄 Migrating to JIRA Cloud

If your JIRA instance has migrated from Server/DC to Cloud (e.g., *.atlassian.net), update the following config values:

jiaz config set auth_type basic # for auth via email
jiaz config set server_url <new_server_url>
jiaz config set jira_sprintboard_id <new_board_id>
jiaz config set user_token <your_new_cloud_token>
jiaz config set user_email <your_email_address>

📝 Note: Generate a new API token for Cloud from Atlassian API Tokens. The jira_sprintboard_id changes across migrations — find the new ID from your Cloud board URL.

Custom field IDs (story points, sprints, epic links, etc.) are auto-discovered from the new instance on first use — no manual updates needed.