Configuration
supercheck.config.ts reference and project structureEdit
The CLI uses a TypeScript configuration file with full IntelliSense via defineConfig().
| File | Purpose |
|---|---|
./supercheck.config.ts | Project configuration (checked into the repo) |
./supercheck.config.local.ts | Local overrides (gitignored, optional) |
Config files must never contain tokens. The CLI scans for token patterns (sck_live_*, sck_trigger_*, sck_test_*) and rejects any config containing them.
The CLI rejects unknown keys in typed configuration sections so misspellings surface during config validate or a sync operation. Provider-specific config maps remain extensible.
Full Example
import { defineConfig } from '@supercheck/cli'
export default defineConfig({
schemaVersion: '1.0',
project: {
organization: '019c1fe3-0a0a-7ae9-884d-61baea139786',
project: '019c1fe3-0a0f-7089-97b3-12990d78a9ee',
},
api: {
baseUrl: process.env.SUPERCHECK_URL ?? 'https://app.supercheck.io',
},
tests: {
playwright: {
testMatch: '_supercheck_/playwright/**/*.pw.ts',
},
k6: {
testMatch: '_supercheck_/k6/**/*.k6.ts',
},
},
monitors: [
{
id: '019c3643-9495-7d66-a463-1c0d42d4520e',
name: 'API Health Monitor',
type: 'http_request',
target: 'https://api.example.com/health',
frequencyMinutes: 5,
enabled: true,
config: {
method: 'GET',
timeoutSeconds: 30,
expectedStatusCodes: '200-299',
locationConfig: {
locations: ['local'],
},
},
alertConfig: {
enabled: true,
alertOnFailure: true,
alertOnRecovery: true,
notificationProviders: ['019c22b5-6df9-79b7-b415-db8317b1bd0b', '019c22b5-a812-7acc-9f23-46f7904d2c2a'],
},
tags: ['api', 'production'],
},
],
requirements: [
{
title: 'Homepage loads for anonymous visitors',
description: 'The marketing homepage renders without errors.',
priority: 'high',
tags: ['web', 'smoke'],
externalId: 'PROJ-123',
externalUrl: 'https://tracker.example.com/PROJ-123',
tests: ['_supercheck_/playwright/homepage-check.019a1234-abcd-7000-8000-000000000001.pw.ts'],
},
],
statusPages: [
{
name: 'Example Status',
status: 'published',
headline: 'Example system status',
language: 'en',
timezone: 'UTC',
branding: { bodyBackgroundColor: '#FFFFFF', fontColor: '#111827', greens: '#16A34A', reds: '#DC2626' },
notifications: { allowEmailSubscribers: true, allowRssFeed: true },
components: [
{ name: 'API', description: 'Public REST API', monitors: ['API Health Monitor'], position: 0 },
],
},
],
tags: [{ name: 'api' }, { name: 'production' }, { name: 'web' }, { name: 'smoke' }],
jobs: [
{
id: '01912345-abcd-7000-8000-000000000001',
name: 'Nightly E2E Suite',
tests: ['_supercheck_/playwright/homepage-check.019a1234-abcd-7000-8000-000000000001.pw.ts'],
jobType: 'playwright',
cronSchedule: '0 2 * * *',
alertConfig: {
enabled: true,
alertOnFailure: true,
alertOnSuccess: true,
notificationProviders: ['019c22b5-6df9-79b7-b415-db8317b1bd0b'],
},
},
],
})Precedence
Settings resolve in this order, highest priority first:
| # | Source | Examples |
|---|---|---|
| 1 | CLI flags | --url, --config |
| 2 | Environment variables | SUPERCHECK_URL, SUPERCHECK_ORG, SUPERCHECK_PROJECT |
| 3 | supercheck.config.local.ts | Local overrides (deep-merged) |
| 4 | supercheck.config.ts | Project defaults |
To use a specific file (.ts, .js or .mjs): supercheck deploy --config ./configs/staging.config.ts
Project Structure
Tests live in _supercheck_/, grouped by runner:
my-project/
├── _supercheck_/
│ ├── playwright/
│ │ ├── homepage-check.019a1234-abcd-7000-8000-000000000001.pw.ts # Playwright test (slug + UUID)
│ │ └── api-check.019a1234-abcd-7000-8000-000000000002.pw.ts # Playwright API test
│ ├── k6/
│ │ └── load-test.019a1234-abcd-7000-8000-000000000003.k6.ts # k6 performance test
├── supercheck.config.ts
└── package.json| Extension | Runner | Example |
|---|---|---|
*.pw.ts | Playwright | _supercheck_/playwright/homepage-check.019a1234-abcd-7000-8000-000000000001.pw.ts |
*.k6.ts | k6 | _supercheck_/k6/load-test.019a1234-abcd-7000-8000-000000000003.k6.ts |
Test files pulled from the cloud use slug.{uuid}.pw.ts and slug.{uuid}.k6.ts. The UUID keeps paths stable across renames, while the slug makes files easy to identify locally.
Test metadata annotations
supercheck pull writes // @title, // @priority (low, medium, high) and // @tags (comma-separated tag names) in the header of each test script: the leading run of // lines, or inside a multi-line JSDoc block at the very top (a single-line /** ... */ header is left alone). @priority and @tags elsewhere in the script are ignored; @title is read from the first match anywhere. They are local metadata: the CLI strips them before comparing or sending the script, including with test create --file and test update --file. deploy applies @priority (any letter case) and @tags; if an annotation is absent, the remote value is left alone. To remove all tags from a test, use supercheck test tag remove.
// @title Homepage Check
// @priority high
// @tags smoke, webValidate and Deploy
| Command | What it does |
|---|---|
supercheck config validate | Validate config syntax and schema |
supercheck config print | Print the resolved configuration (with env var expansion) |
supercheck diff | Preview changes between config and server state |
supercheck deploy | Create/update resources; --dry-run previews, --delete removes remote resources absent from config, --force skips confirmation |
supercheck destroy | Tear down all managed resources; --dry-run previews, --force confirms |
Resources are reconciled by database id. Pulled resources include their id (UUID); new resources omit it and are created on deploy. diff includes notification provider settings such as webhook bodyTemplate, so review it before deploying and keep test scripts as editable source files.
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.
Before sync operations, the CLI verifies configured organization and project IDs or slugs against the authenticated API context, catching config that would point at a different project than the token.
Schema Reference
Deployment State
Successful deploys record server-assigned IDs for created resources, and the current names of updated or unchanged managed resources, in supercheck.state.json. Commit and share this file with CI so later deployments manage the same resources. Do not commit the temporary supercheck.state.json.lock.