QA CLI

coldtea-qa is Coldtea QA from the command line. Tests are written in plain English, runs happen in Coldtea's cloud, and the exit code is the verdict, so a CI step needs nothing beyond the command itself.

Install

npm install -g @coldtea/qa
cqa --version

The package installs two names for the same binary: coldtea-qa, and cqa for short — fewer tokens for the agents that call it most.

Needs Node 20.6 or newer. The package has no runtime dependencies.

Auth

Create an API key in the Coldtea app under Settings, then:

export COLDTEA_API_KEY=coldtea_sk_...
coldtea-qa whoami

The key identifies your organization. There is no organization flag, and the API rejects a request that names one. Prefer the environment variable over --api-key: a flag is visible in ps while the process runs, in shell history, and in any CI log that echoes the step.

First run

coldtea-qa projects list                  # find a project id
export COLDTEA_PROJECT_ID=prj_...
coldtea-qa groups create "Smoke"          # tests live in groups
coldtea-qa tests create "Buy an item with a saved card" --url https://shop.example
coldtea-qa run test mqt_... --wait        # exit code is the verdict

The test description is the test. Say what a person would do, in English.

Behind a login? Store the secret with credentials create, point an environment at the site with environments create, then give the group that environment with groups update --environment. To run on every pull request, rules create.

Exit codes

The split between 2 and 4 is the one to script against: 2 may succeed on retry, 4 never will.

Machine output

--json prints one JSON document on stdout, in the API's own envelope: { "data": ..., "meta": { "requestId": ... } }. List commands carry meta.nextCursor; page by copying it until it is null, never by counting rows. Errors go to stderr in the same shape, { "error": ..., "meta": { "requestId": ... } }, so stdout stays parseable on failure. Quote meta.requestId when reporting a problem.

Environment

Commands

Generated from the CLI's own command table, so this list cannot drift from the binary. cqa help <family> prints the full help for any group below.

cqa whoami

Show the organization and key this CLI authenticates as.

cqa projects list

List the organization's projects.

cqa projects create <name>

Create a project.

cqa projects get <id>

Show one project.

cqa projects link-repo <id>

Link a repository (--provider, --repository-id).

cqa tests list

List a project's tests.

cqa tests create <description>

Create a test (one target flag).

cqa tests get <id>

Show one test.

cqa tests update <id>

Edit a test; --group moves it.

cqa tests delete <id>

Archive a test (cancels its runs).

cqa groups list

List a project's groups.

cqa groups create <name>

Create a group.

cqa groups get <id>

Show one group.

cqa groups update <id>

Rename or re-describe a group.

cqa groups delete <id>

Archive a group and its tests.

cqa run test <id>

Start one test run (--wait follows it).

cqa run group <id>

Start a batch of a group's tests.

cqa runs get <id>

Show one run and why it ended that way.

cqa runs stop <id>

Stop a run that is still going.

cqa runs list

List runs (filters mirror the API).

cqa builds upload <file>

Upload a build (--platform required).

cqa builds get <id>

Show one build and its artifact.

cqa merge <src> --into <id>

Merge a project into a survivor.

cqa environments list

List where runs can open.

cqa environments create <name>

Create a web environment (--url).

cqa environments get <id>

Show one environment.

cqa environments update <id>

Edit one (--acknowledge for rules).

cqa environments delete <id>

Delete one (refused while in use).

cqa rules list

List a project's trigger rules.

cqa rules create <name>

Create a trigger rule (one --when).

cqa rules update <id>

Rename, enable or disable a rule.

cqa rules delete <id>

Delete a rule.

cqa credentials list

List stored secrets (metadata only).

cqa credentials create <name>

Store a secret (piped on stdin).

cqa credentials rename <id>

Rename one (--name).

cqa credentials rotate <id>

Replace the secret (piped on stdin).

cqa credentials delete <id>

Delete one (refused while in use).

cqa repositories list

List repositories we can see (for link-repo).

cqa apps list

List a project's mobile apps.

cqa skips list

Why a project's rules did not run.