/k6-manage

name: k6-manage
description: Interact with Grafana Cloud k6 (GCk6) — manage load tests, test runs, scripts, projects, schedules, env vars, fetch metrics or logs, and run scripts locally — using the `gcx` CLI (or direct curl when gcx is unavailable). Use this skill whenever the user mentions a k6 cloud test or run, asks to list/edit/create/start/abort k6 load tests, wants to fetch logs or metrics for a test run, manage k6 project limits or schedules, run a k6 script locally or via `k6 cloud run`, or needs to call any `/cloud/v6/`, `/cloud/v5/`, or k6-app Loki endpoint against a Grafana Cloud stack. Trigger even when the user doesn't explicitly say "gcx" or "API" — phrases like "why did my k6 test fail", "show me logs for run X", "bump VUh limit on project Y", or "update my k6 script" all qualify.

Grafana Cloud k6 — interaction reference

The default path is the `gcx` CLI. When gcx isn't installed, every endpoint here is still reachable via direct curl against k6's public hosts — see §1.2 for the auth-header and host-translation rules. Two principles shape the rest:

• **gcx owns Grafana-side auth (when present).** It injects the right

headers on every call, so you should not set auth headers yourself. The only header you ever set by hand is `X-K6TestRun-Id`, on Loki log queries (§4), browser screenshot/file fetches (§6), and Tempo trace queries (§7) — anything else gets overwritten or causes conflicts. In curl mode the auth headers are manual; see §1.2.

• **Reach for `gcx k6 ...` subcommands first.** They wrap the common

paths with friendlier ergonomics and handle pagination. Discover what's available with `gcx help-tree k6` (and drill in further with `gcx help-tree k6 <subcommand>`); fall back to `gcx api` only when no subcommand exists for what you need.

---

1. Authentication

1.1 With gcx (default)

gcx login --context <ctx>                # one-time OAuth, browser flow
gcx --context <ctx> config check         # expect "✔ Connectivity: online"

Once a context is logged in, every `gcx api ...` and `gcx k6 ...` call inherits its auth state. If a call returns *"Invalid or expired token — run gcx login to refresh"*, the OAuth session has lapsed — re-run `gcx login --context <ctx>`.

1.2 Without gcx — direct curl

Check `command -v gcx` first. If it's missing, every endpoint in this skill is still reachable directly against k6's public hosts — three things change versus the gcx examples elsewhere:

• **Auth headers are manual.** Set both on every call:
• `Authorization: Bearer <k6_token>`
• `X-Stack-ID: <int>`
• **Hosts replace the plugin proxy.**
• REST (`/cloud/v6/...`, `/cloud/v5/...`, `/cloud-resources/v1/...`,

`/insights/...`) → `https://api.k6.io`

• Logs (Loki) and traces (Tempo) → `https://cloudlogs.k6.io`
• **No `/api/plugins/k6-app/resources/{cloud,logs,insights}` prefix.**

Drop it; everything after that prefix in the gcx examples is the real k6 path. The doubled `cloud/cloud/` quirk from §2 collapses to a single `/cloud/` — the first one was just the proxy route.

Obtaining the credentials

Don't guess these — prompt the user once per session for:

1. **k6 API token** — long-lived bearer; the same value `gcx k6 auth token` would print when gcx is configured. 2. **Stack** — either the integer **stack ID** (used directly in `X-Stack-ID`) or a Grafana **stack URL** (e.g. `https://myorg.grafana.net`). If the user supplies a URL, resolve it to an ID once with `GET /cloud/v6/auth`, which takes the URL in the `X-Stack-Url` header and returns `{stack_id, default_project_id}`:

   STACK_ID=$(curl -sS https://api.k6.io/cloud/v6/auth \
     -H "Authorization: Bearer $K6_TOKEN" \
     -H "X-Stack-Url: $STACK_URL" \
     | jq -r '.stack_id')

Cache the resolved ID for the session — every subsequent call needs it in `X-Stack-ID`. (Note: `/cloud/v6/auth` is the *only* endpoint that takes `X-Stack-Url` instead of `X-Stack-ID` — it's how you cross the gap from "user-known URL" to "API-required ID".)

Translation cheat-sheet

| gcx form (plugin proxy) | curl form (direct) | |------------------------------------------------------------------------------------------|--------------------------------------------------------------------------| | `gcx api /api/plugins/k6-app/resources/cloud/cloud/v6/test_runs/123` | `curl https://api.k6.io/cloud/v6/test_runs/123 -H ...` | | `gcx api /api/plugins/k6-app/resources/cloud/cloud/v5/test_runs/<id>/metrics` | `curl https://api.k6.io/cloud/v5/test_runs/<id>/metrics -H ...` | | `gcx api /api/plugins/k6-app/resources/cloud/cloud-resources/v1/files/index` | `curl https://api.k6.io/cloud-resources/v1/files/index -H ...` | | `gcx api /api/plugins/k6-app/resources/insights/insights/api/v1/testrun/<id>/executions` | `curl https://api.k6.io/insights/api/v1/testrun/<id>/executions -H ...` | | `gcx api /api/plugins/k6-app/resources/logs/api/v1/query_range?...` | `curl https://cloudlogs.k6.io/api/v1/query_range?... -H ...` | | `gcx api /api/plugins/k6-app/resources/logs/api/v1/tempo/api/search?...` | `curl https://cloudlogs.k6.io/api/v1/tempo/api/search?... -H ...` |

In every `-H ...` slot above, send both auth headers: `-H "Authorization: Bearer $K6_TOKEN" -H "X-Stack-ID: $STACK_ID"`.

Notes:

• Endpoint-specific headers gcx leaves to you — `X-K6TestRun-Id` on

log, trace, and files endpoints (§4, §6, §7) — are still required *in addition* to the auth pair.

• The `gcx api` flag quirks in §2 (spill envelope, `--json field`

filtering, `-o` for output format) don't apply to curl. Use plain curl flags: `-o file` to save body, `--data-binary @file` for PUT payloads, `-w '%{http_code}'` for s