Run tests

Use the Spanline CLI on your laptop or in CI to execute k6 and send results to your workspace. Install a release build from spanline.dev/cli — you do not need a source checkout for normal use.

The app catalogs and observes; the CLI runs the test.

New to Performance? Start with Getting started, then return here for flags and CI.

Install

  1. Download the spanline binary for your OS from your team’s release channel (or spanline.dev/cli).
  2. Put it on your PATH and confirm:
spanline version

Sign in

  1. In the app, open Account → API tokens and create a token with permission to run Performance tests.
  2. On your machine:
spanline auth login --token sl_…
spanline auth workspace list
spanline auth workspace use <workspace-name-or-id>

Release binaries default to Spanline Cloud (https://api.spanline.dev). Enterprise self-host: add --api https://api.<your-domain> on login, or set SPANLINE_API in CI — see Enterprise self-host below.

Your login is stored locally for the CLI. Confirm the workspace with auth workspace list if Overview shows empty data — wrong workspace is a common first-run mistake.

CI environment variables

Prefer env vars over interactive login in pipelines:

Variable Purpose
SPANLINE_TOKEN API token
SPANLINE_API API base URL when not Spanline Cloud (Enterprise self-host)
SPANLINE_WORKSPACE Active workspace id
SPANLINE_APP_URL Optional UI origin for “View in UI” links (when not api.* → app.*)
SPANLINE_ORG_RSA_PRIVATE_KEY_FILE PEM path to decrypt sealed secrets (default ~/.config/spanline/org-rsa-private.pem)
SPANLINE_ORG_RSA_PRIVATE_KEY Inline PEM for CI (prefer the file env interactively)
SPANLINE_K6_BIN / SPANLINE_K6_VERSION Override k6 binary / version
K6_CLOUD_TOKEN Only if you use --executor k6-cloud

Enterprise self-host

If your organization runs Spanline on your own servers (signed deployment license), the CLI must target your API origin — not api.spanline.dev.

Laptop (once):

spanline auth login \
  --api https://api.acme.example \
  --token sl_…
spanline auth workspace use <workspace-name-or-id>

CI:

export SPANLINE_API=https://api.acme.example
export SPANLINE_TOKEN=sl_…
export SPANLINE_WORKSPACE=…
spanline test run --scenario-id … --ci

When the browser UI is not on the usual app.<same-domain> host, set SPANLINE_APP_URL (for example https://spanline.acme.example) so “View in UI” links resolve correctly.

Server install (deployment license, SPANLINE_PUBLIC_URL, first-run setup) is separate from the CLI — see Customer self-host install.

Run a single script

From a local file:

spanline test run ./checkout.js --name smoke

From a scenario already in Spanline (matches the Overview snippet):

spanline test run --scenario-id <scenario-uuid>

Pin a saved scenario version when you need a known script snapshot:

spanline test run --scenario-id <scenario-uuid> --version-id <version-uuid>

Useful flags

Flag When to use
--sync Upsert the named scenario in Spanline from your local script before running (local-first CI)
--name Scenario name used with --sync (and for display)
--options-json Pass a k6 options file (schedule/stages live here when not embedded in the script)
--env Pick an environment by name
--ci Non-interactive mode for pipelines
--upload-artifacts Attach log/bundle files to the run
--version-id Pin a scenario version snapshot
--no-install-k6 Fail if k6 is missing instead of downloading
--executor k6-cloud Local execution with k6 Cloud reporting (K6_CLOUD_TOKEN required)

Local-first CI example:

spanline test run ./script.js --sync --name smoke \
  --options-json ./options.json --ci --upload-artifacts

After the runner starts, open Performance → Runs (or Overview) to watch live metrics.

Sync is a CLI operation. The app scenario editor lets you paste and edit scripts; it does not “sync from disk.” Use --sync --name when your source of truth is a file in git.

Collections and matrix

Create the collection and click Start run in the app first (Performance → Collections) — that creates a pending collection-run plan. Then execute:

spanline test collection-run --id <collection-run-id> --ci
spanline test collection-run --id <collection-run-id> --ci --upload-artifacts

Or create a plan and run from a collection id in one step:

spanline test collection-run --collection-id <collection-id> --ci

Export evidence:

spanline test matrix --id <collection-run-id> --format csv -o matrix.csv
spanline test matrix --id <collection-run-id> --format json -o matrix.json

In the app, Matrix offers Export CSV. JSON export is available from the CLI as shown above.

Webhook handoff (test watch)

When an external system creates a collection-run plan via a collection webhook, a runner can wait and pick it up:

spanline test watch --once --upload-artifacts

Use --interval when your automation docs specify a poll interval. Pair this with inbound webhook secrets from the collection editor — see Guides.

k6

The CLI expects k6 on the machine. If it is missing, the CLI downloads a supported build into the user cache unless you pass --no-install-k6. Prefer installing k6 yourself in locked-down CI images.

Sealed secrets in CI

If your organization uses sealed secrets for Connections or environment values, CI must provide the organization private key your admins issued — usually SPANLINE_ORG_RSA_PRIVATE_KEY or the file env above. Never commit that key to git. Most contributors only need a valid API token day to day. See Access & secrets.