xray-cli 0.1.0

Command-line interface for Xray Cloud test management

xray-cli

Command-line interface for Xray Cloud test management.

A zero-dependency Python CLI that talks to the Xray Cloud API (GraphQL + REST) to manage test executions, tests, runs, results, preconditions, test sets, test plans, and folders — all from your terminal.

Installation

Requires Python 3.8+.

pip install .

This installs the xray command.

Quick Start

1. Set your Xray API credentials (get them from Xray Cloud → API Keys):

export XRAY_CLIENT_ID="your-client-id"
export XRAY_CLIENT_SECRET="your-client-secret"

Or create a config file (see Configuration below).

2. Run a command:

xray execution list --limit 5
xray test get XSP-123
xray run list --execution XSP-456 --failed-only

Global Flags

Flag	Short	Description
--version		Print version and exit
--config PATH		Path to config file (default: auto-discover .xray-cli.ini)
--json		Output in JSON format instead of human-readable text
--verbose	-v	Enable verbose/debug output
--quiet	-q	Suppress all non-error output
--timeout SECONDS		Request timeout in seconds (default: from config or 30)

Note: Global flags can be placed anywhere in the command, e.g. xray --json execution list or xray execution list --json.

Commands

xray execution — Test Execution Operations

List executions:

xray execution list [--jql JQL] [--limit N] [--start N]

Create an execution:

xray execution create --project XSP --summary "Regression run" [--test XSP-100 --test XSP-101]

Argument	Required	Description
--project	Yes	Jira project key
--summary	Yes	Summary for the new execution
--test	No	Test issue key to include (repeatable)

xray test — Test Operations

Get a single test:

xray test get XSP-123

List tests:

xray test list [--jql JQL] [--limit N] [--start N]

xray run — Test Run Operations

List runs:

xray run list [--test XSP-123] [--execution XSP-456] [--status PASS] [--failed-only] [--limit N] [--start N]

Argument	Description
--test	Filter by test issue key (repeatable)
--execution	Filter by execution issue key (repeatable)
--status	Filter by run status name
--failed-only	Show only failed/aborted runs

Update run status:

xray run update-status <run_id> <status>

Status values: PASS, FAIL, TODO, EXECUTING, ABORTED, etc.

Add evidence to a run:

xray run add-evidence <run_id> path/to/screenshot.png

xray results — Import Test Results

Import Xray JSON results:

xray results import xray-json results.json [--project XSP] [--execution XSP-456]

Import JUnit XML results:

xray results import junit results.xml [--project XSP] [--execution XSP-456]

xray precondition — Precondition Operations

xray precondition list [--jql JQL] [--limit N] [--start N]

xray test-set — Test Set Operations

xray test-set list [--jql JQL] [--limit N] [--start N]

xray test-plan — Test Plan Operations

xray test-plan list [--jql JQL] [--limit N] [--start N]

xray folder — Folder Operations

xray folder list --project XSP [--path /MyFolder] [--limit N] [--start N]

Configuration

Config File

Create .xray-cli.ini in your project directory or home directory:

[xray]
client_id = YOUR_CLIENT_ID
client_secret = YOUR_CLIENT_SECRET

[defaults]
project_key = XSP
output = text
timeout_seconds = 30
page_limit = 50

See xray-cli.ini.example for a full annotated template.

You can also specify a config file explicitly:

xray --config /path/to/config.ini execution list

Environment Variables

All settings can be set via environment variables:

Variable	Config Key
XRAY_CLIENT_ID	client_id
XRAY_CLIENT_SECRET	client_secret
XRAY_AUTH_URL	auth_url
XRAY_GRAPHQL_URL	graphql_url
XRAY_IMPORT_BASE_URL	import_base_url
XRAY_PROJECT_KEY	project_key
XRAY_OUTPUT	output
XRAY_TIMEOUT	timeout_seconds
XRAY_PAGE_LIMIT	page_limit

Precedence

Settings are resolved in this order (highest wins):

1. CLI flags (--json, --timeout)
2. Environment variables (XRAY_*)
3. Config file (.xray-cli.ini)
4. Built-in defaults

Output Formats

By default, output is human-readable text. Use --json for machine-readable JSON:

# Human-readable
xray test list --limit 3

# JSON output (pipe to jq, etc.)
xray --json test list --limit 3 | jq '.results[].issue_key'

Exit Codes

Code	Meaning
0	Success
2	Usage / validation error
3	Configuration error
4	Authentication error
5	Network / transport error
6	API / resolution error
7	Import error

Running Tests

PYTHONPATH=src python3 -m unittest discover -s tests

License

MIT