Overview

The QA Sphere CLI (qasphere, published as the qas-cli npm package) is the official command-line interface for QA Sphere. It exposes the full public API and supports four primary workflows:

Ad-hoc terminal use — run qasphere api <resource> <action> commands to inspect or change QA Sphere state. Every command prints JSON to stdout for easy piping into tools like jq. See Public API.
Scripts and CI/CD automation — orchestrate projects, folders, test cases, milestones, runs, and results from shell scripts and pipelines. See CI/CD Integrations.
Test result uploads — push JUnit XML, Playwright JSON, and Allure result directories at the end of an automated run. See Result Upload.
AI coding agents — a bundled skill lets Claude Code, Cursor, and similar agents drive QA Sphere through the CLI in natural language. See Agent Skill.

Open source

qas-cli is open source: github.com/Hypersequent/qas-cli. Track development, report issues, and contribute on GitHub.

Installation

Requirements

Node.js 22.0.0 or higher. No other runtime is needed — the CLI works alongside Python, Go, Java, or any other test stack.

Installing Node.js

If you don't already have Node.js, install it via your system package manager:

macOS: brew install node
Ubuntu/Debian: sudo apt install nodejs npm
Windows / other: download from nodejs.org

Via npm (global)

npm install -g qas-cli

Verify:

qasphere --version

Update later with:

npm update -g qas-cli

Via npx

npx qas-cli <command>

On first use you'll be prompted to download the package. npx qas-cli works in every context the qasphere command does.

Verify:

npx qas-cli --version

npx caching

npx caches packages. To force the latest version, run npx clear-npx-cache (or pin a specific version, e.g. npx qas-cli@0.5.0).

Shell completion

The CLI ships with tab completion for commands and options. Append the completion script to your shell profile:

Zsh:

qasphere completion >> ~/.zshrc

Bash:

qasphere completion >> ~/.bashrc

Restart your shell (or source the profile) and pressing Tab will autocomplete commands and flags.

The QA Sphere API allows 20 requests per second per user, shared across all of that user's API keys and OAuth authorizations. Exceeding it returns 429 Too Many Requests. See API Rate Limiting for the full set of limits.

The CLI handles this for you. On a 429 it waits and retries automatically, honoring the Retry-After header the API sends and otherwise backing off exponentially — up to 5 retries over roughly 30 seconds. Result uploads are also deliberately paced: attachments upload at most 3 batches at a time, and results are posted in sequential batches rather than all at once. A normal upload, even one with thousands of results, stays well under the limit.

Upgrade if you are on an older version

Automatic retry on 429 was added in v0.8.0. On v0.7.0 and earlier the CLI fails immediately when rate limited, which typically shows up as a failed upload step in CI. Check your version with qasphere --version and upgrade with npm update -g qas-cli.

If you still hit rate limits on a current version, the usual cause is several CI jobs running concurrently under the same QA Sphere user. Because the limit is per user rather than per API key, adding more API keys will not help — give the parallel jobs separate user accounts instead.

Where to next

Auth — log in via OAuth or configure an API key.
Public API — call the full QA Sphere REST API from the terminal.
Result Upload — upload JUnit XML, Playwright JSON, or Allure results into a run. Framework guides and CI/CD examples live in the Integrations section.
Agent Skill — register the CLI with Claude Code, Cursor, and other coding agents.
CI/CD Integrations — wire the CLI into GitHub Actions, GitLab CI/CD, or Bitbucket Pipelines.