CLI Reference

Quick setup

1. 1. Get access

   No account yet? Sign up — new accounts go through a quick manual approval before the dashboard unlocks.

2. 2. Create a project and get your API key

   • Go to app.oyaplus.com/analytics/projects → + New project → name it
   • Your API key is generated right then and shown with a copy button — grab it now
   • You can always find it again later under Settings → API Keys

3. 3. Install the CLI

   Requires Node.js 14 or later.

   npm install -g oyacloud

   Copy

4. 4. Choose your test framework

   Pick the one you actually use — steps 5 and 7 below change to match it.

   Playwright (TypeScript/JS)

   playwright_ts

   Playwright (Python)

   playwright_py

   TestNG (Java)

   testng_java

   pytest (Python)

   pytest_python

   JUnit (Java)

   junit_java

   Cypress

   cypress_js

5. 5. Configure your reporter

   Pick a framework in step 4 above to see this step.

6. 6. Save your API key

   Running on CI? Set a secret/variable named exactly OYACLOUD_API_KEY in your CI platform, and every future command needs no --api-key flag at all.

   • GitLab CI / CircleCI — that's the whole thing, both expose it to your job automatically
   • GitHub Actions / Jenkins — needs one extra line to map it in, pick your platform below to see it
   GitHub ActionsGitLab CICircleCIJenkins

   Repo secrets aren’t auto-exposed as env vars — map it explicitly, once, in the workflow:

   env:
     OYACLOUD_API_KEY: ${{ secrets.OYACLOUD_API_KEY }}

   Copy

   Not setting up a CI secret at all? Just pass --api-key YOUR_KEY directly on the command instead — or, for local/manual runs, save it once:

   oyacloud config set-key YOUR_PROJECT_API_KEY

   Copy

7. 7. Upload your results

   oyacloud upload --framework <framework> --environment staging --results-dir <results-dir>

   Copy

   Pick a framework in step 4 above to fill in the exact command.

   A green 🎉 Upload completed successfully! here means the file was received and queued — it doesn't mean it was parsed correctly. Processing happens afterward, asynchronously; if the build doesn't show up looking right, your OyaCloud dashboard is the real source of truth, not this terminal output.

   Two things worth knowing before you rely on this data:

   • Every build is auto-classified as PR / post-merge / regression from your CI trigger on most platforms — see Automatic build-type detection below for exactly how, or what to do if your platform isn't one of them.
   • Running a scoped/filtered subset of your suite (a tag filter, a specific folder) rather than the full thing? Pass --suite-name, or it silently merges into your full-suite history — see the --suite-name guide below.

Automatic build-type detection

OyaCloud figures out whether a run is a PR, a post-merge build, or a scheduled/regression run directly from your CI platform’s own trigger signal — not by guessing from branch names. How much of that is automatic depends on which platform you’re on:

Passing --build-type or setting OYACLOUD_BUILD_TYPE always overrides detection, on any platform.

The three build types

The same command works for every scenario below and every supported CI platform:

• Branch, commit, PR number, and author are all auto-detected (see "What gets auto-detected" below)
• build_type is detected too, on most platforms — see the tiers above
• --environment is the one flag that's genuinely yours to set — point it at whatever CI variable your own pipeline already uses (shown here as $ENVIRONMENT, illustrative — use your own variable name)

oyacloud upload \
  --framework <framework> \
  --environment $ENVIRONMENT \
  --results-dir <results-dir>

<framework> and <results-dir> are whatever you picked in Quick setup steps 4-5 above. No --api-key shown — see Quick setup step 6 above for how that gets picked up automatically.

What gets auto-detected

Different from build_type detection above — this is the underlying data (branch, commit, PR number, target branch, author) the CLI reads directly from your CI platform's own environment variables and attaches to every build:

• Nothing to configure — pulled straight from real environment variables
• Nothing ever guessed — a field with no real source (marked — below) is just left blank, exactly like omitting the flag
• Passing the flag explicitly always overrides whatever was detected

• GitHub Actions — PR number detection covers both pull_request and pull_request_target events.
• CircleCI* — PR number isn't always populated for same-repo (non-fork) PRs, depending on project settings. CircleCI's own documented limitation, not something OyaCloud's CLI can work around.
• Jenkins — only gets branch/PR-number/target-branch on a Multibranch Pipeline job configured with PR discovery. A plain freestyle job has none of these (commit still works, via the Git plugin).

Reference

All flags

Network requirements

On a self-hosted CI runner behind a firewall, allowlist outbound HTTPS to both of these — uploads use both on every run:

Supported frameworks

Cypress note: Cypress's own test runner doesn't produce OyaCloud-readable output directly — add mocha-junit-reporter (the standard way to get CI-consumable output from Cypress, since Mocha is its test runner underneath) and point --results-dir at wherever it writes its XML.

Short aliases: testng, pytest, junit, and cypress also work as shorthand for testng_java, pytest_python, junit_java, and cypress_js.

--suite-name guide

--suite-name sets the display label shown in the dashboard and becomes the run scope — the key used to group and compare builds over time. It's equally optional across every build type (PR, post-merge, regression, local) — nothing about build type makes it required.

Troubleshooting