Metadata-Version: 2.4
Name: jiraxray-cli
Version: 0.1.1
Summary: Agent-friendly CLI for Xray Cloud test management in Jira.
Project-URL: Homepage, https://jaysisley.dev
Project-URL: Repository, https://github.com/reignonu13/agent-jiraXray-cli
Project-URL: Issues, https://github.com/reignonu13/agent-jiraXray-cli/issues
Project-URL: Documentation, https://github.com/reignonu13/agent-jiraXray-cli/tree/main/docs
Author-email: Jay Sisley <jay.sisley@icloud.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,cli,jira,qa,testing,xray
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: pyyaml>=6.0.2
Description-Content-Type: text/markdown

# jiraxray-cli

`jiraxray-cli` is a Python CLI for helping QA teams migrate Zephyr tests to Xray Cloud and manage Xray test assets in Jira. It is built for functional testers, automation testers, QA engineers, scripts, and AI agents that need compact, predictable access to migration and Xray workflows.

The package installs one command:

- `jiraxray-cli`

## Install From PyPI

```bash
python -m pip install jiraxray-cli
jiraxray-cli --help
```

With `uv` as an isolated command-line tool:

```bash
uv tool install jiraxray-cli
jiraxray-cli --help
```

## Goals

- Inspect Zephyr Squad Excel exports before migration.
- Create reviewable Zephyr-to-Xray mapping files.
- Transform source tests into local Xray import plans.
- Validate and preview migration plans before any Xray writes.
- Manage Xray Cloud tests, steps, sets, plans, executions, results, and imports.
- Queue and poll Xray REST v2 bulk test imports for reviewed test libraries.
- Give agents a compact command manifest so they can plan without loading large docs.
- Support repeatable automation suites for known Xray workflows.
- Keep secrets out of local project files.

## Install From A Checkout

Prerequisites:

- Python 3.11 or newer
- `uv`
- Git

Windows PowerShell:

```powershell
git clone https://github.com/reignonu13/agent-jiraXray-cli.git
cd agent-jiraXray-cli
py -m pip install --user uv
uv sync
uv run jiraxray-cli --help
```

macOS:

```bash
git clone https://github.com/reignonu13/agent-jiraXray-cli.git
cd agent-jiraXray-cli
python3 -m pip install --user uv
uv sync
uv run jiraxray-cli --help
```

Linux:

```bash
git clone https://github.com/reignonu13/agent-jiraXray-cli.git
cd agent-jiraXray-cli
python3 -m pip install --user uv
uv sync
uv run jiraxray-cli --help
```

## Credentials

Secrets are read only from environment variables:

```bash
export XRAY_CLIENT_ID="..."
export XRAY_CLIENT_SECRET="..."
export XRAY_REGION="global" # global, us, eu, or au
```

Optional:

```bash
export XRAY_BASE_URL="https://xray.cloud.getxray.app"
export JIRA_BASE_URL="https://your-domain.atlassian.net"
export JIRA_EMAIL="you@example.com"
export JIRA_API_TOKEN="..."
export JIRA_PROJECT_KEY="QA"
```

## Agent Discovery

```bash
jiraxray-cli commands
jiraxray-cli command "migrate transform"
jiraxray-cli commands --json
jiraxray-cli diagnose --json
jiraxray-cli diagnose --live --json
```

`diagnose --live` validates Jira and Xray connectivity when both credential sets
are present.

## Zephyr To Xray Migration

The first migration workflow is read-only. It produces mapping files, import
plans, and Markdown reports for review.

```bash
jiraxray-cli zephyr inspect --source zephyr-export.xlsx --out inspect.md
jiraxray-cli migrate map init --source zephyr-export.xlsx --project-key QA --out zephyr-to-xray.yaml
jiraxray-cli migrate map validate --mapping zephyr-to-xray.yaml
jiraxray-cli migrate transform --source zephyr-export.xlsx --mapping zephyr-to-xray.yaml --out xray-import-plan.json
jiraxray-cli migrate validate --input xray-import-plan.json
jiraxray-cli migrate preview --input xray-import-plan.json --out migration-preview.md
```

## AI Tool Setup

Generate project-local guidance for Codex, Claude Code, GitHub Copilot, or all:

```bash
jiraxray-cli init --tool all --json
jiraxray-cli init --tool codex --path /path/to/suite --suite-name "Payments QA" --json
jiraxray-cli init --tool claude --json
jiraxray-cli init --tool copilot --json
```

Generated skills are token-efficient: each `SKILL.md` stays short and points to focused `references/*.md` files that agents load only when needed.

## Automation Suites

Workflows live under `.jiraxray-cli/workflows/*.yaml`.

```bash
jiraxray-cli suite init
jiraxray-cli suite list
jiraxray-cli suite validate smoke-import
jiraxray-cli suite run smoke-import --dry-run --json
jiraxray-cli workflow validate-import --format junit --path report.xml --json
jiraxray-cli workflow sync-library --source tests.yaml --project-key DEMO --dry-run --json
```

## Xray REST v2 Bulk Test Import

Use this when you already have an Xray bulk test import JSON file and want Xray
to queue it as an asynchronous import job:

```bash
jiraxray-cli tests import-bulk --path xray-tests.json --json
jiraxray-cli tests import-status --job-id JOB_ID --json
```

The CLI validates that the payload is JSON and does not exceed Xray Cloud REST
v2's documented 1000-test-per-request limit before sending it.

## Simple Jira And Xray Operational Flow

These commands mirror the concise workflow exposed by the inspected Jira Xray
Tools MCP server while keeping this project CLI-first:

```bash
jiraxray-cli issues create --type Bug --summary "Checkout fails" --json
jiraxray-cli issues summary --issue QA-123 --json
jiraxray-cli issues link --inward QA-200 --outward QA-123 --type Test --json
jiraxray-cli executions create --project-key QA --summary "Smoke execution" --json
jiraxray-cli executions add-tests --execution QA-200 --tests QA-201,QA-202 --json
jiraxray-cli testruns get --execution QA-200 --test QA-201 --wait --json
jiraxray-cli testruns upload-evidence --run RUN_ID --files screenshot.png --json
```

## Development

```bash
make sync
make check
make package
```

See `docs/api-contract.md` for the offline Xray API contract checks and
`docs/production-readiness.md` for the current readiness backlog. See
`docs/publishing.md` for build, install, and publish instructions. See
`CHANGELOG.md` for release notes.
