CLI reference

The CLI is a thin client over the API. It starts a run, waits, and gives you the result and the failure reports. It needs Node 22 or newer and has no other dependencies.

InstallCopy Anchor Link

npx outqube --help          # no install
npm install -g outqube      # or global

Sign inCopy Anchor Link

In CI, create an API key with the trigger scope in Settings, API keys and store it as the secret OUTQUBE_API_KEY. See Authentication.

On your machine, run outqube login. It asks for the key without showing it, checks it and saves it for your user. outqube whoami shows the last four characters of the key, its app and the API address, and outqube logout removes the saved key. The key is never printed.

For Outqube on your own domain, use --api-url or OUTQUBE_API_URL. The default is https://app.outqube.com.

CommandsCopy Anchor Link

Run outqube COMMAND --help for the options of a command. --json works on every read command: stdout holds one JSON document and progress goes to stderr.

Options for run and rerunCopy Anchor Link

--fail-on, --timeout, --cancel-on-timeout and --junit need --wait.

Waiting for a runCopy Anchor Link

With --wait the CLI polls with a growing delay (2 to 15 seconds), prints one line per change, then a summary and the summary of each failure report.

• Ctrl-C or SIGTERM cancels the run and exits 130 or 143. A second signal exits at once.
• After --timeout it stops waiting and exits 4. The run keeps going unless you also pass --cancel-on-timeout.
• --junit out.xml writes one test case per test, with the report summary as the failure message. It is also written on a timeout or a signal.

Exit codesCopy Anchor Link

--fail-on failed ignores run errors: only failed tests exit 1.

CI metadataCopy Anchor Link

The commit, branch, pull request and repo come from GitHub Actions, GitLab CI and Azure Pipelines automatically and are sent with source: cli. For a pull request the commit is the head commit, not the merge commit. --commit, --branch, --pr and --repo override them. With the GitHub App, runs that carry the repo and commit show up on the pull request's Outqube check.

CI examplesCopy Anchor Link

- name: Outqube
  run: npx outqube run --suite smoke --url ${{ vars.STAGING_URL }} --wait --junit out.xml
  env:
    OUTQUBE_API_KEY: ${{ secrets.OUTQUBE_API_KEY }}
- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: outqube-junit
    path: out.xml

The CI guide explains each of these.

JSON outputCopy Anchor Link

With --json, run --wait prints { run, failures: [{ test_run_id, name, outcome, summary, report_markdown }] }. An error is one line on stderr: {"error":{"message","exit_code","code","request_id"}}. The shapes of runs, tests and reports are those of the API. Write scripts the way the CLI does: treat an outcome you do not know as not passed.

Output safetyCopy Anchor Link

Everything the CLI prints passes through a filter that replaces the API key, removes escape sequences and control characters, and changes a line that starts with :: or ## so a CI system does not run it as a command. Text from pages and reports cannot affect your terminal or your build.

Client headerCopy Anchor Link

Every request carries an x-outqube-client header with the CLI version and the OS, plus the CI system and repo in CI, or the machine's name outside it. Organisation admins see it under each key in Settings, API keys, to tell where a key is used. It never holds the key or your command. To cut a machine off, revoke its key.

Next stepsCopy Anchor Link

• Run Outqube from CI: a full nightly workflow.
• Authentication: keys and scopes.
• GitHub App: get the result on the pull request too.