Command Reference
Complete reference for all Supercheck CLI commandsEdit
Every command is supercheck <group> <command>. Run supercheck <command> --help for options.
| Group | Commands |
|---|---|
| Global flags | --json, --quiet, --wide, --show-secrets, … |
| Agent-first operation | skills, capabilities, schema config |
| Authentication | login, link, onboard, discover, plan, ci init, agent install, whoami, logout |
| Configuration | init, config validate, validate, config print |
| Jobs | job list/get/create/update/delete/run/trigger/keys |
| Runs | run list/get/permissions/status/wait/stream/cancel |
| Tests | test list/get/create/update/delete/tags/validate/run/execute/status |
| Monitors | monitor list/get/status/results/stats/create/update/delete |
| Variables, Tags | var list/get/set/delete, tag list/create/delete |
| Notification providers | notification list/get/create/update/delete/test |
| Alerts and audit | alert history, audit |
| AI SRE | incident, sre, service |
| Monitoring-as-Code | pull, diff, deploy, destroy |
| Utilities | health, locations, upgrade, doctor |
Global Flags
Available on all commands, before or after the subcommand:
supercheck --json job trigger <job-id> --wait
supercheck --quiet whoami
supercheck config validate --json| Flag | Description |
|---|---|
--json | Output in JSON format (for CI/CD scripting) |
--envelope | Include pagination metadata with JSON list results; requires --json |
--show-secrets | Disable redaction for sensitive fields in command output |
--quiet | Suppress non-essential output (only IDs and errors) |
--wide | Show tables without width limits |
--no-color | Disable ANSI colors |
--debug | Enable debug logging |
-v, --version | Show version |
Config-aware commands (for example config, diff, deploy, pull, validate, destroy) also accept --config <path> to point at a specific config file.
Exit Codes
| Code | Meaning | Example |
|---|---|---|
0 | Success | Job completed successfully |
1 | General error | Test failed, monitor down |
2 | Authentication error | Invalid token, expired token |
3 | Configuration error | Missing config, invalid schema |
4 | Network / API error | API unreachable, 5xx response |
5 | Timeout | Operation exceeded timeout |
130 | Interrupted | Ctrl+C during a stream |
An operation that requires confirmation exits 3 when declined or when input closes (ABORTED), and exits 3 with CONFIRMATION_REQUIRED when confirmation is unavailable in a non-interactive session. Review its plan, then pass --force to apply the already-authorized change. Authentication errors continue to use exit code 2.
Agent-first operation
| Command | What it does | Key flags |
|---|---|---|
supercheck skills [topic] | Print the offline workflow index or a focused guide (local, sync, configure, execute, investigate). Bundled with the CLI version; no credentials | — |
supercheck skills install | Write a small .agents/skills/supercheck/SKILL.md pointer. Existing skill files are preserved unless --force | --path <directory>, --force |
supercheck capabilities | Report CLI version, local workflow capabilities, and whether credentials are present | --online |
supercheck schema config | Describe the installed configuration schema without loading repository code | --json |
supercheck skills
supercheck skills local
supercheck skills sync
supercheck skills configure
supercheck skills execute
supercheck skills investigate
supercheck capabilities --json
supercheck capabilities --online --json
supercheck schema config --json--online verifies the current API context with one request; it does not prove every server feature is available or that the token has permission for every operation. Diagnostic commands tolerate an invalid project config: an explicit, environment, or stored URL identifies the target and skips config loading. Otherwise a valid config supplies its API URL; if config loading fails, diagnostics warn in human-readable output and fall back to the default API URL.
Machine-readable plans and writes
diff --json and deploy --dry-run --json return plans on stdout. Successful deploys return per-resource results, including server-assigned IDs and the state-file path. pull --dry-run --json describes the remote resources and config path it would write. Other mutation --dry-run --json commands return the proposed request payload.
JSON errors on stderr carry a stable code agents can branch on, with retryable and suggested nextActions where useful. Existing error strings and exit codes are unchanged.
| Code | Meaning |
|---|---|
AUTH_REQUIRED | No credential; run supercheck login |
TOKEN_INVALID | Credential expired, revoked or rejected; run supercheck login --reauth |
PERMISSION_DENIED | Authenticated but not allowed (role or project) |
SUBSCRIPTION_REQUIRED | No active plan; a person must choose one in the dashboard |
SPENDING_LIMIT_REACHED | The organization's spending limit blocks execution |
RATE_LIMITED / SERVICE_UNAVAILABLE | Retryable |
VALIDATION_FAILED | The request was rejected as invalid |
CONFIRMATION_REQUIRED | A write needs --force |
PAYMENT_REQUIRED | The server answered 402 without a recognised reason; run supercheck plan |
AUTHORIZATION_PENDING | login without --json or a terminal started a browser login that is not approved yet (exit 2); approve it, then run login again |
DEVICE_CODE_DENIED, DEVICE_CODE_EXPIRED, DEVICE_CODE_CONSUMED, DEVICE_LOGIN_UNVERIFIED, TOKEN_LIMIT_REACHED | Browser-login outcomes |
CONTEXT_MISMATCH | The config's API URL, organization or project does not match the logged-in context; see supercheck link |
In a non-interactive session, a write requiring confirmation refuses with exit code 3 and a CONFIRMATION_REQUIRED error. Review the preview before explicitly passing --force. The CLI checks that config organization/project match the authenticated API context before sync operations.
Deploy records returned IDs in supercheck.state.json, keyed by API origin and actual organization/project. Share this generated mapping with CI so subsequent deploys manage the same resources. The transient .lock coordinates deploys only on a shared local filesystem; do not commit it. Names alone do not establish ownership; pull an existing resource or set its explicit ID. Deploy does not rename local test files.
Authentication
| Command | What it does | Key flags |
|---|---|---|
supercheck login | Sign in through your browser, or store a CLI token | --token, --url, --reauth, --no-browser, --wait, --timeout |
supercheck link | Point supercheck.config.ts at the org and project you are logged in to | --dry-run, --force |
supercheck onboard | Read-only status of the current directory and the single next command | — |
supercheck discover | Bounded, read-only facts about the repository | --root <directory> |
supercheck plan | Show whether the organization has an active subscription | — |
supercheck ci init --github | Write .github/workflows/supercheck.yml | --path <file>, --force |
supercheck agent install | Install the Supercheck skill for a coding agent | --target, --path, --pointer, --force |
supercheck whoami | Show the authenticated project, organization and role | — |
supercheck logout | Clear stored credentials | — |
supercheck login
supercheck login --token <token>
supercheck whoami
supercheck logoutwhoami includes token identity and expiry when your role permits viewing API keys (user, token name, API URL, expiry); read-only users can still verify their context.
Configuration
| Command | What it does | Key flags |
|---|---|---|
supercheck init | Create supercheck.config.ts and the _supercheck_/ folder | --force, --skip-install, --skip-examples, --pm <manager> |
supercheck config validate | Validate the configuration file schema | --offline |
supercheck validate | Validate local test scripts using the same rules as Playground | — |
supercheck config print | Print the resolved configuration with environment variable expansion | --offline |
supercheck init
supercheck init --force # Overwrite existing config
supercheck init --skip-install # Skip dependency installation
supercheck init --skip-examples # Skip example test files
supercheck init --pm pnpm # Use specific package manager (npm, pnpm, yarn, bun)
supercheck config validate
supercheck config validate --offline
supercheck validate
supercheck config print
supercheck config print --offline--offline validates or prints a local-only config without API credentials. Both modes require an existing config file; --offline skips cloud project identity checks. config print redacts sensitive provider values, including webhook URLs and config headers; monitor URLs remain visible and credential headers are masked.
Jobs
| Command | What it does | Key flags |
|---|---|---|
job list | List jobs in the current project | --page (1), --limit (50) |
job get <job-id> | Get job details | — |
job create | Create a job | --name (required), --tests (required), --description, --type, --schedule, --dry-run |
job update <job-id> | Update job configuration | --name, --description, --schedule, --dry-run |
job delete <job-id> | Delete a job with confirmation | --force |
job run | Run a job immediately, bypassing the cron schedule | --id, --local, --cloud, --offline, --playwright-config |
job trigger <job-id> | Trigger a job with a trigger key, optionally wait | --wait, --timeout (300) |
job keys | List, create and revoke trigger keys | create --name --expires-in, delete |
supercheck job list --page 2 --limit 10
supercheck job create --name "Nightly E2E" --tests <test-id> --schedule "0 2 * * *"
supercheck job create --name "Smoke Tests" --tests id1,id2 --type k6 --dry-run
supercheck job update <job-id> --schedule "0 3 * * *" --dry-run
supercheck job delete <job-id> --force
supercheck job run --id <job-id>
supercheck job run --id <job-id> --local # Run locally
supercheck job run --id <job-id> --cloud # Run in the cloud
supercheck job run --id "Nightly E2E" --local --offline
supercheck job trigger <job-id>
supercheck job trigger <job-id> --wait --timeout 300
supercheck --json job trigger <job-id> --wait
supercheck job keys <job-id>
supercheck --show-secrets job keys create <job-id> --name "CI Trigger"
supercheck --show-secrets job keys create <job-id> --name "Temp Key" --expires-in 86400
supercheck job keys delete <job-id> <key-id>Runs
| Command | What it does | Key flags |
|---|---|---|
run list | List job runs. Runs of a test executed directly (test execute) are not listed; follow those with run get <runId> or --wait | --page, --limit, --job <job-id>, --status (queued, running, passed, failed, error, blocked) |
run get <run-id> | Get run details | — |
run permissions <run-id> | Get run access permissions | — |
run status <run-id> | Quick status check | — |
run wait <run-id> | Wait for an existing run to reach a terminal state; never starts or retriggers a run | --timeout <seconds> (300) |
run stream <run-id> | Watch live console output | --idle-timeout (60, min 10) |
run cancel <run-id> | Cancel a running execution | — |
supercheck run list --job <job-id> --status failed --limit 20
supercheck run get <run-id>
supercheck run wait <run-id> --timeout 600
supercheck run stream <run-id> --idle-timeout 120
supercheck run cancel <run-id>run stream: failed, cancelled, blocked, or missing runs return a nonzero exit code. Ctrl-C cancels the client stream; --json emits NDJSON events. --idle-timeout is the number of seconds to wait with no data before timing out.
Tests
| Command | What it does | Key flags |
|---|---|---|
test list | List tests | --page, --limit, --search (title), --type, --priority |
test get <test-id> | Get test details | --include-script |
test create | Create a test from a script file | --title, --file (both required), --type, --description, --priority, --dry-run |
test update <test-id> | Update a test | --title, --file, --type, --description, --priority, --dry-run |
test delete <test-id> | Delete a test with confirmation | --force |
test tags <test-id> | List tags for a test | — |
test tag add <test-id> <tags...> | Add tags (names or IDs), keeping existing tags; applied atomically on the server, so concurrent tag changes are not lost (older servers fall back to read-then-replace) | — |
test tag remove <test-id> <tags...> | Remove tags (names or IDs); unknown or unassigned tags are ignored | — |
test validate | Validate a script without creating it | --file, --type |
test run | Run tests locally | --file, --all, --type (browser, performance), --offline, --playwright-config |
test execute <test-id> | Execute one deployed test in the cloud; returns the run ID, or waits with --wait | --location <code>, --wait, --timeout (300) |
test status <test-id> | Stream live status events | --idle-timeout (60, min 10) |
Test types: browser, performance, api, database, custom. Priorities: low, medium, high.
supercheck test list --search "checkout" --type browser
supercheck test list --priority high
supercheck test tag add <test-id> smoke checkout
supercheck test tag remove <test-id> checkout
supercheck test get <test-id> --include-script
supercheck test create --title "Homepage Check" --file ./_supercheck_/playwright/homepage-check.<id>.pw.ts --type browser
supercheck test update <test-id> --title "Updated Title" --file ./updated-script.pw.ts
supercheck test update <test-id> --type api --dry-run
supercheck test update <test-id> --description "New description" --dry-run
supercheck test delete <test-id> --force
supercheck test validate --file ./_supercheck_/playwright/homepage-check.<id>.pw.ts --type browser
supercheck test run --file ./_supercheck_/playwright/homepage-check.<id>.pw.ts
supercheck test run --all --type browser
supercheck test run --all --type performance
supercheck test run --offline --file ./_supercheck_/playwright/homepage.pw.ts
supercheck test run --all --offline --playwright-config ./playwright.config.ts
supercheck test execute <test-id>
supercheck test execute <test-id> --wait --timeout 600
supercheck test execute <test-id> --location us-east --wait
supercheck test status <test-id> --idle-timeout 120Use supercheck test run --file <path> for local execution, or supercheck job trigger <id> for cloud execution.
Requirements
Requirements track what the product must do and which tests prove it. supercheck requirement (alias requirements) manages them from the terminal; you can also manage them as code with requirements[] in supercheck.config.ts (see Configuration). They need a server version that includes the requirements REST API.
| Command | What it does | Key flags |
|---|---|---|
requirement list | List requirements with coverage status | --search, --priority, --status (covered, failing, missing), --page (1), --page-size (50) |
requirement get <id> | Get a requirement with its tags, linked tests and coverage | — |
requirement create | Create a requirement | --title (required, 1-500 characters), --description, --priority, --tag, --external-id, --external-url, --test |
requirement update <id> | Update a requirement; only the flags you pass change | create flags, --clear-tags, --clear-tests |
requirement delete <id> | Delete a requirement with confirmation | --force |
requirement link <id> <test-ids...> | Link tests, keeping existing links (up to 100 per call) | — |
requirement unlink <id> <test-ids...> | Unlink tests | — |
requirement coverage [id] | Coverage for one requirement, or a count per coverage status | — |
requirement export | Export requirements as CSV to stdout or a file | --output <file>, --force |
supercheck requirement list --priority high --status failing
supercheck requirement get <requirement-id>
supercheck requirement create --title "Users can reset their password" --priority high --tag auth,security --test <test-id>
supercheck requirement update <requirement-id> --priority medium
supercheck requirement update <requirement-id> --tag auth --clear-tests
supercheck requirement link <requirement-id> <test-id-1> <test-id-2>
supercheck requirement unlink <requirement-id> <test-id-1>
supercheck requirement coverage
supercheck requirement export --output requirements.csv
supercheck requirement delete <requirement-id> --force--tag and --test repeat or take comma-separated values (up to 10 tags of 50 characters, and 100 tests). On update they replace the whole set; --clear-tags and --clear-tests empty it and cannot be combined with them. Requirement tags that do not exist yet are created by the server. export refuses to overwrite a file unless you pass --force, never writes through a symbolic link, and leaves the file readable only by you. With --json and no --output, it prints { "format": "csv", "content": "..." }.
Extracting requirements from an uploaded document (PDF, DOCX, Markdown or TXT) with AI is available in the dashboard only. The CLI and MCP server do not upload documents.
Monitors
| Command | What it does | Key flags |
|---|---|---|
monitor list | List all monitors | --page, --limit |
monitor get <monitor-id> | Get monitor details | — |
monitor status <monitor-id> | Current status (quick view) | — |
monitor results <monitor-id> | Recent check results | --page (1), --limit (20) |
monitor stats <monitor-id> | Performance statistics | — |
monitor create | Create a monitor | --name (required), --url, --type, --test-id, --port, --protocol, --interval-minutes, --timeout, --method, --dry-run |
monitor update <monitor-id> | Update a monitor | --name, --url, --interval-minutes, --timeout, --method, --active, --dry-run |
monitor delete <monitor-id> | Delete with confirmation | --force |
supercheck monitor list --page 2 --limit 10
supercheck monitor results <monitor-id> --page 2 --limit 20
supercheck monitor create --name "API Health" --url https://api.example.com/health --type http_request --interval-minutes 5
supercheck monitor create --name "Website" --url https://example.com --dry-run
supercheck monitor create --name "TLS port" --type port_check --url example.com --port 443
supercheck monitor create --name "Browser journey" --type synthetic_test --test-id <test-uuid>
supercheck monitor update <monitor-id> --interval-minutes 1 --active false
supercheck monitor update <monitor-id> --name "Updated" --method POST --dry-run
supercheck monitor delete <monitor-id> --forceVariables
| Command | What it does | Key flags |
|---|---|---|
var list | List project variables | — |
var get <key> | Get a variable by key | — |
var set <key> <value> | Create or update a variable | --secret, --value-stdin, --description |
var delete <key> | Delete a variable | --force |
supercheck var set API_KEY sk-secret-value --secret
printf '%s' "$API_KEY" | supercheck var set API_KEY --secret --value-stdin
supercheck var set DB_URL postgres://... --description "Database connection string"
supercheck var delete <key> --force--secret encrypts the value. Prefer --value-stdin for secrets so they do not end up in shell history or process arguments.
Tags
| Command | What it does | Key flags |
|---|---|---|
tag list | List tags | — |
tag create <name> | Create a tag | --color |
tag delete <id> | Delete a tag | --force |
supercheck tag create <name> --color "#3B82F6"
supercheck tag delete <id> --force # Skip confirmationNotification Providers
notifications is an alias for notification.
| Command | What it does | Key flags |
|---|---|---|
notification list | List providers | — |
notification get <id> | Get provider details | — |
notification create | Create a provider | --type, --name (both required), --payload |
notification update <id> | Update a provider | --name, --type, --payload |
notification delete <id> | Delete a provider | --force |
notification test | Send a test notification | --type, --payload (one payload option required) |
Types: email, slack, webhook, telegram, discord, teams. --payload is a JSON object; --data and the legacy --config are aliases.
supercheck notification create --type slack --name "Slack Alerts" \
--payload '{"webhookUrl":"https://hooks.slack.com/..."}'
supercheck notification update <id> --name "Updated Name" --payload '{...}'
supercheck notification update <id> --type webhook --payload '{...}'
supercheck notification delete <id> --force
supercheck notification test --type slack --payload '{"webhookUrl":"https://hooks.slack.com/..."}'Alerts & Audit
alerts is an alias for alert.
| Command | What it does | Key flags |
|---|---|---|
alert history | View alert history | --page (1), --limit (50) |
audit | View audit logs (admin only) | --page (1), --limit (20), --search (by action), --action (filter by action type) |
supercheck alert history --page 2 --limit 20
supercheck audit --page 2 --limit 50 --action "notification_provider_created"
supercheck audit --search "deploy"AI SRE
AI SRE commands use the active project from the CLI token and preserve the same tenant and RBAC boundaries as the dashboard. Plural aliases incidents and services are also supported.
| Command | What it does | Key flags |
|---|---|---|
incident list | List incidents | --status, --severity |
incident get <ref> | Get an incident | — |
incident timeline <ref> | Incident timeline | — |
incident resolve <ref> | Resolve with a required comment | --comment, --force |
sre triage <ref> | Classify an incident | — |
sre investigate <ref> | Start an asynchronous deep investigation | --live-connectors |
sre brief <ref> | Stream an evidence brief | --idle-timeout |
sre ask "<question>" | Ask Copilot (read-only) | --incident <ref>, --live-connectors, --idle-timeout |
sre status <runId> | Follow a triage or accepted investigation | — |
service list/get/health/dependencies | Read-only service catalog | needs sre_service:view |
<ref> is the number shown by incident list or a UUID. Numbers resolve within the CLI token's project; they are not row positions. Use incident list --json to see UUIDs. Manual triage and investigations are enabled by default with a configured AI provider; existing operator opt-outs remain effective (503 feature_disabled identifies the setting to change, and you recreate containers after changing .env). Automatic AI work remains opt-in.
Incidents
supercheck incident list --status investigating --severity sev1
supercheck incident list --status open # every incident that is not resolved
supercheck incident get <incident-number-or-uuid>
supercheck incident timeline <incident-number-or-uuid>
supercheck incident resolve <incident-number-or-uuid> --comment "Traffic restored after rollback"Resolution prompts for confirmation and stores the required comment in the incident timeline and audit log. Use --force only in reviewed automation.
Triage and investigation
supercheck sre triage <incident-number-or-uuid>
supercheck sre investigate <incident-number-or-uuid>
supercheck sre investigate <incident-number-or-uuid> --live-connectors
supercheck sre brief <incident-number-or-uuid>
supercheck sre brief <incident-number-or-uuid> --idle-timeout 120
supercheck sre status <runId>Deep investigation is asynchronous: a successful command returns an accepted investigation-run ID. Follow progress with incident get and incident timeline, or sre status <runId> (requires a matching app release with the investigation-status endpoint). --live-connectors enables configured read-only telemetry tools only when the caller also has sre_connector:investigate permission.
Copilot
supercheck sre ask "Why did checkout latency increase?"
supercheck sre ask "Summarize the strongest evidence" --incident <incident-number-or-uuid>
supercheck sre ask "Check current telemetry" --incident <incident-number-or-uuid> --live-connectorsCopilot is read-only. Use an incident your token can access, and add --live-connectors only when you have connector investigation permission. --idle-timeout controls stream inactivity (minimum 10 seconds). Ctrl-C cancels the client stream. Global --json emits NDJSON events for automation. Streamed errors and AI-provider unavailability return a nonzero exit code for both Copilot and evidence briefs.
Service catalog
supercheck service list
supercheck service get <service-id>
supercheck service health <service-id>
supercheck service dependencies <service-id>These commands are read-only and require sre_service:view.
Monitoring-as-Code
| Command | What it does | Key flags |
|---|---|---|
pull | Pull remote resources into local config and files | --dry-run, --force, --tests-only, --config-only |
diff | Preview changes between local config and server state | --delete, --no-delete |
deploy | Push configuration to the API | --dry-run, --delete, --no-delete, --force, --verify, --verify-timeout <seconds> |
destroy | Tear down all managed resources defined with IDs in the local config, including notification providers, requirements and status pages | --dry-run, --force |
supercheck pull
supercheck pull --dry-run
supercheck pull --force
supercheck pull --tests-only
supercheck pull --config-only
supercheck diff
supercheck deploy
supercheck deploy --dry-run # Preview without applying
supercheck deploy --delete # Delete remote resources absent from config (and components absent from a declared list)
supercheck deploy --force # Skip confirmation
supercheck deploy --force --verify # Then run each created/updated browser test once in the cloud
supercheck destroy --dry-run # Preview resources to be deleted
supercheck destroy --force # Confirm and delete resourcessupercheck destroy requires --force to confirm deletion, or --dry-run to preview. Bare supercheck destroy errors without --force.
diff and deploy preserve remote resources absent from config by default. Use diff --delete to preview pruning, then deploy --delete to apply it. Pruning includes resources created outside this config. --no-delete remains supported. --force skips the confirmation prompt; keep test scripts as editable source files and review supercheck diff before deploying.
Utilities
| Command | What it does | Key flags |
|---|---|---|
health | Check API health | --url |
locations | List available execution locations | — |
upgrade | Upgrade the CLI to the latest release | --tag <tag>, --package-manager <pm>, -y, --yes, --dry-run |
doctor | Check dependencies and configuration | --strict, --fix |
supercheck health
supercheck health --url https://supercheck.yourdomain.com
supercheck locations
supercheck upgrade
supercheck upgrade --tag <version> # Install a specific version
supercheck upgrade --package-manager pnpm # Use specific package manager (npm, pnpm, yarn, bun)
supercheck upgrade --dry-run # Preview without installing
supercheck upgrade -y # Skip confirmation
supercheck doctor
supercheck doctor --strict # Exit non-zero unless deps, config and server-verified credentials are in place
supercheck doctor --fix # Auto-install Playwright browsers; prints install hints for other depsupgrade --tag defaults to latest and accepts explicit versions; --dry-run previews the upgrade command without executing.