Usage guide

How test engineers use the CLI with Xray and AI.

Set up the CLI, let an AI assistant discover the allowed commands, run dry-runs first, then write to Xray only when the result has been checked. Plain English, no Python packaging required.

Start setup Jump to examples
01

Install

Install it and check it can run.

You don't need to understand Python packaging. You need Python 3.11 or newer, Git, and access to the repository or release package.

Install from GitHub

# Install the command from GitHub.
$ python -m pip install "git+https://github.com/reignonu13/agent-jiraXray-cli.git"
$ jiraxray-cli --help

Install from a checkout

# Use this when working from the repo.
$ git clone https://github.com/reignonu13/agent-jiraXray-cli.git
$ cd agent-jiraXray-cli
$ python -m pip install --user uv
$ uv sync
$ uv run jiraxray-cli --help
02

Connect

Connect Jira and Xray without storing secrets in files.

The CLI reads secrets from environment variables. A project profile can store safe defaults, but API tokens and client secrets stay outside the repo.

macOS and Linux

export XRAY_CLIENT_ID="..."
export XRAY_CLIENT_SECRET="..."
export XRAY_REGION="global"
export JIRA_BASE_URL="https://your-domain.atlassian.net"
export JIRA_EMAIL="you@example.com"
export JIRA_API_TOKEN="..."
export JIRA_PROJECT_KEY="QA"

Windows PowerShell

$env:XRAY_CLIENT_ID="..."
$env:XRAY_CLIENT_SECRET="..."
$env:XRAY_REGION="global"
$env:JIRA_BASE_URL="https://your-domain.atlassian.net"
$env:JIRA_EMAIL="you@example.com"
$env:JIRA_API_TOKEN="..."
$env:JIRA_PROJECT_KEY="QA"
verify
# Local check first, live connection check second.
$ jiraxray-cli diagnose --json
$ jiraxray-cli diagnose --live --json
03

AI pattern

Use the AI tool in a controlled pattern.

Treat the AI as a helper that plans and prepares the work. The CLI is the controlled tool layer. The test engineer still reviews the output before any writes happen.

01
Discover

The AI runs commands --json to learn the allowed actions.

02
Check

It runs diagnose --json to confirm setup before doing work.

03
Dry-run

Suites are run with --dry-run first.

04
Review

The engineer checks the JSON, Markdown report, or planned steps.

05
Run

Only then does someone run the command that writes to Xray.

Habit to keep

Good AI usage means the AI can suggest and prepare, but the CLI keeps the shape of the work tight: named commands, known inputs, JSON output, dry-runs, and explicit writes. It works from GitHub Copilot, Claude, Codex, or any assistant that can run a terminal command.

04

Existing automation

Put it beside the automation suite you already have.

The CLI is not the test runner. Keep using the runner your team already trusts. The CLI gives that runner — and any AI helper — a controlled way to describe the test work in Xray.

01
Test source

Manual test library, Playwright, pytest, Cypress, Postman, Robot, or another suite.

02
Team mapping

Decide which scenarios are manual-only, automated, or both.

03
CLI suite

Capture the Xray update steps in .jiraxray-cli/workflows/*.yaml.

04
Dry-run

Show the planned Xray work before changing tests, plans, executions, or results.

05
Update Xray

Run the approved command and keep the output for the release record.

Example suite file

Stored in your repo, reviewed in PRs, run by humans, AI, or CI.

# .jiraxray-cli/workflows/regression-sync.yaml
name: regression-sync
description: Keep regression tests and results aligned in Xray.
inputs:
  project_key:
    type: string
    required: true
steps:
  - name: sync reviewed manual tests
    command: workflow sync-library
    args:
      source: tests/manual-regression.yaml
      project_key: ${project_key}
      dry_run: true
05

Service fit

Know where the CLI sits before using it.

Jira and Xray are the products testers use every day. The CLI is the controlled bridge that lets a terminal, an automation job, or an AI assistant work alongside them.

Jira Cloud

Project and issue context: stories, bugs, plans, executions, and team process.

Xray Cloud

Test management on top of Jira: tests, runs, evidence, results, sets, and plans.

jiraxray-cli

The safe command layer for manual users, existing suites, and AI assistants.

06

Scenario alignment

How manual and automated scenarios line up in Xray.

The suite becomes the shared shape of the work. Manual tests, automated results, executions, and evidence all point back to the same test intent.

Manual scenario path

Use this when a test engineer owns the scenario wording and expected result.

# Check the manual test library first.
$ jiraxray-cli workflow sync-library --source tests.yaml --project-key QA --dry-run
# Run the sync after review.
$ jiraxray-cli workflow sync-library --source tests.yaml --project-key QA --json

Automated scenario path

Use this when the automation has produced a result file for Xray.

# Validate the automation result file before importing.
$ jiraxray-cli workflow validate-import --format junit --path report.xml
$ jiraxray-cli results import --format junit --path report.xml --json
Same plan, same view

Manual evidence and automated result files both land in Xray, against the same tests, in the same execution view. The CLI keeps that alignment without forcing every test to be automated.

07

Examples

Common work, shown as real commands.

Examples a test engineer should be able to copy, change, and run. Each block defaults to dry-run or read-only behaviour, so it's safe to try before committing.

Inspect a Zephyr export

Produces a local report for review. Does not write to Xray.

$ jiraxray-cli zephyr inspect --source zephyr-export.xlsx --out inspect.md
$ jiraxray-cli migrate map init --source zephyr-export.xlsx --out zephyr-to-xray.yaml
$ jiraxray-cli migrate transform --mapping zephyr-to-xray.yaml --out xray-import-plan.json
$ jiraxray-cli migrate preview --input xray-import-plan.json --out migration-preview.md

Create or update manual tests

For reviewed manual scenarios and step wording.

$ jiraxray-cli tests create --project-key QA --summary "User can sign in" --test-type Manual
$ jiraxray-cli tests update-steps --issue-id 12345 --steps-file steps.json
$ jiraxray-cli sets add-tests --set-id 10001 --test-ids 12345

Create execution + attach evidence

When a tester has run a scenario and needs evidence on the Xray run.

$ jiraxray-cli executions create --project-key QA --summary "Smoke execution" --test-ids QA-101
$ jiraxray-cli testruns get --execution QA-200 --test QA-101 --wait
$ jiraxray-cli testruns upload-evidence --run RUN_ID --files screenshot.png,notes.txt

Run a repeatable suite

Use dry-run first. That habit keeps the workflow safe with AI.

$ jiraxray-cli suite list
$ jiraxray-cli suite run regression-sync --dry-run --json
$ jiraxray-cli suite run regression-sync --json
08

Quick reference

The commands you'll come back to.

A copyable cheatsheet of the work this CLI is built around. Bookmark this section.

Cheatsheet

Add --dry-run --json to any write command to preview it.
Discover commandsjiraxray-cli commands --json
Check setup (local)jiraxray-cli diagnose --json
Check live connectionjiraxray-cli diagnose --live --json
Read an issuejiraxray-cli issues summary --issue QA-123 --json
Search testsjiraxray-cli tests search --jql "project = QA" --json
Sync manual libraryjiraxray-cli workflow sync-library --source tests.yaml --dry-run
Validate a result filejiraxray-cli workflow validate-import --format junit --path report.xml
Import resultsjiraxray-cli results import --format junit --path report.xml --json
Create executionjiraxray-cli executions create --project-key QA --summary "Smoke" --test-ids QA-101
Upload evidencejiraxray-cli testruns upload-evidence --run RUN_ID --files shot.png
Run a saved suitejiraxray-cli suite run regression-sync --dry-run --json
Back to overview View on GitHub