supaguard CLI reference

IMPORTANT: Always use --json flag when calling CLI commands. Parse JSON output for structured data. Errors go to stderr as { "error": "message" }. Exit code 0 = success, 1 = failure.

auth

supaguard login

Opens browser for OAuth authentication. No --json flag.

supaguard logout [--json]

Revokes token and clears local config.

{ "success": true }

supaguard whoami [--json]

Shows current user and active organization.

{ "user": { "name": "...", "email": "..." }, "org": { "id": "uuid", "slug": "acme-corp", "name": "Acme Corp" } }

supaguard orgs [--json]

Lists organizations. In interactive mode, allows switching the active org.

{ "organizations": [{ "id": "uuid", "slug": "...", "name": "..." }], "activeOrg": { "id": "...", "slug": "...", "name": "..." } }

checks

supaguard checks list [--status STATUS] [--limit N] [--json]

Lists monitoring checks for the active organization.

{ "checks": [{ "id": "...", "slug": "...", "name": "...", "status": "ACTIVE", "type": "browser", "latestRun": {...} }], "total": 10, "limit": 50, "offset": 0 }

supaguard checks test <file> [--json]

Tests a Playwright script in the cloud runner. Does NOT deploy.

{ "status": "passed" | "failed", "durationMs": 1234, "error": "...", "artifactUrls": { "recording": "...", "screenshot": "...", "trace": "..." } }

On failure, read error for a friendly message and artifactUrls for debugging artifacts.

supaguard checks create <file> --name NAME --locations LOCATIONS --cron CRON [--alert-policy ID] [--skip-test] [--json]

Tests the script first (unless --skip-test), then deploys as a recurring monitoring check.

• --name (required): human-readable check name
• --locations (required): comma-separated region IDs (e.g., eastus,northeurope)
• --cron (required): cron expression for schedule (e.g., "*/5 * * * *")
• --alert-policy: alert policy ID to attach
• --skip-test: skip the test-before-deploy step

{ "check": { "id": "uuid", "slug": "abc123", "name": "...", "status": "ACTIVE", "type": "browser", "dashboardUrl": "https://supaguard.app/dashboard/..." } }

supaguard checks update <id> [--name NAME] [--script FILE] [--locations LOCATIONS] [--cron CRON] [--alert-policy ID] [--json]

Updates an existing check. If --script is provided, the new script is tested first.

{ "check": { "id": "...", "slug": "...", "name": "...", "status": "..." } }

supaguard checks delete <id> [--force] [--json]

Deletes a check. Prompts for confirmation unless --force is set.

{ "deleted": true }

supaguard checks status <id> [--json]

Shows check details and recent executions.

{ "check": { "id": "...", "name": "...", "status": "...", "type": "..." }, "executions": [{ "id": "...", "status": "...", "durationMs": 1234, "createdAt": "..." }] }

supaguard checks run <id> [--region REGION] [--json]

Triggers an on-demand execution of the check.

{ "executionId": "uuid", "url": "https://supaguard.app/dashboard/..." }

supaguard checks pause <id> [--json]

Pauses a check (sets status to DISABLED).

{ "checkId": "...", "status": "DISABLED" }

supaguard checks resume <id> [--json]

Resumes a paused check (sets status to ACTIVE).

{ "checkId": "...", "status": "ACTIVE" }

modules

supaguard modules list [--json]

Lists shared modules for the active organization.

{ "modules": [{ "id": "...", "path": "pages/LoginPage.ts", "updatedAt": "..." }] }

supaguard modules push <file> [--path MODULE_PATH] [--json]

Uploads or updates a shared module. --path sets the module's import path (e.g., pages/LoginPage.ts).

{ "module": { "id": "...", "path": "...", "createdAt": "..." } }

supaguard modules delete <id> [--force] [--json]

Deletes a module. Prompts for confirmation unless --force.

{ "deleted": true }

alerts

supaguard alerts list [--json]

Lists alert policies for the active organization.

{ "policies": [{ "id": "...", "name": "...", "isDefault": false, "steps": [...] }] }

supaguard alerts create --name NAME --channel TYPE:TARGET [--json]

Creates a simple single-channel alert policy.

Channel formats:

• Slack: --channel slack:#channel-name
• Email: --channel email:team@company.com
• Webhook: --channel webhook:https://hooks.example.com/alert

{ "policy": { "id": "...", "name": "...", "steps": [...] } }

For complex escalation chains (multi-step, delays, SMS, phone), direct the user to the supaguard dashboard.

Framework-specific source code patterns

When analyzing a user's codebase, use these patterns to quickly find routes, components, and testable elements.

Next.js (App Router)

• Routes: app/ directory - each page.tsx is a route, directory structure = URL path
• Components: co-located in app/ or shared in components/
• API routes: app/api/ directory - each route.ts is an endpoint
• data-testid: look in client components ("use client" directive) - server components may not have testids
• Layout: layout.tsx files for shared UI (navbars, sidebars)

Next.js (Pages Router)

• Routes: pages/ directory - each file is a route
• Global layout: _app.tsx
• API routes: pages/api/
• Components: typically in components/ directory

React SPA (CRA / Vite)

• Routes: defined in router config, usually React Router
• Look for route definitions in App.tsx, routes.tsx, or router.tsx
• Single entry point with client-side routing
• Components: src/components/ or feature-based directories

Vue

• Routes: router/index.ts or router/index.js
• Components: components/ or views/ directories
• Look for data-testid or data-test attributes (Vue convention)
• Templates in .vue single-file components

Generic HTML / MPA

• Each HTML file is a page
• Look for <a href> for navigation paths
• Forms are usually the critical flows to monitor
• Check for data-testid attributes in any framework

Shared modules, alerting, regions, and scheduling

shared modules

when to suggest modules

Suggest modules when you notice:

• 2+ checks that share login logic
• Same selectors used across multiple checks (page objects)
• Helper functions reused across checks (waitForAuth, dismissCookieBanner)

module workflow

1. Write the module to /tmp/sg-module-{name}.ts
2. Push: supaguard modules push /tmp/sg-module-{name}.ts --path "pages/LoginPage.ts" --json
3. Import in scripts: import { LoginPage } from './pages/LoginPage';

IMPORTANT: Always ask the user before pushing modules. Suggest, don't auto-push.

module path rules

• Must end in .ts or .js
• Can only contain alphanumeric characters, underscores, hyphens, forward slashes
• Cannot contain .. (no path traversal)
• Cannot start with / (must be relative)
• Pattern: [a-zA-Z0-9_\-/.]+\.(ts|js)

module content rules

Modules follow the same forbidden-import rules as scripts:

• No child_process, fs, net, dgram, cluster, worker_threads, vm, http, https
• No eval(), Function(), process.exit, process.kill, dynamic import()

alerting

basic alerting via CLI

After deploying a check, offer to set up alerting:

# Create an alert policy
supaguard alerts create --name "Critical Alerts" --channel slack:#monitoring --json

# Link the alert policy to a check
supaguard checks update <checkId> --alert-policy <policyId> --json

supported channels

• Slack: --channel slack:#channel-name
• Email: --channel email:team@company.com
• Webhook: --channel webhook:https://hooks.example.com/alert

recommended setup

• Set consecutiveFailuresRequired to 2 (avoids alerting on transient failures)
• Use Slack for immediate notification, email for escalation
• For complex escalation chains (multi-step, delays, SMS, phone): direct the user to the supaguard dashboard

regions

Available regions (use these exact IDs in --locations flag):

For most monitoring: use 2+ regions for geographic coverage.

scheduling

Common cron presets (use in --cron flag):

Recommended default: */5 * * * * (every 5 minutes) with 2+ regions.

Playwright monitoring best practices

monitoring scripts vs test scripts

Monitoring scripts run on a schedule against production. They must be:

• Resilient: handle transient failures (network blips, slow loads, cookie banners)
• Fast: complete in under 60 seconds (runner timeout). Keep scripts lean.
• Observable: meaningful assertions that detect real breakage, not flaky checks

best practices

1. Always start with import { test, expect } from "@playwright/test";
2. Use page.goto(url, { waitUntil: "networkidle" }) for initial page loads
3. Prefer page.getByTestId("x") over CSS selectors
4. Use await expect(element).toBeVisible() before interacting with an element
5. Use explicit waits: page.waitForSelector(), page.waitForResponse()
6. NEVER use page.waitForTimeout() or sleep() - these make checks flaky and waste time
7. Keep one logical flow per check (e.g., login only, not login + checkout + logout)
8. Assert on user-visible outcomes, not internal DOM state
9. Handle common obstacles before proceeding:
   • Cookie consent banners: dismiss or accept
   • Popups/modals: close or interact as needed
   • Loading states: wait for spinners to disappear with await expect(spinner).not.toBeVisible()
10. Use descriptive test names: test("user can complete checkout", ...)

anti-patterns

• Don't assert on CSS classes or style properties (they change with redesigns)
• Don't assert on exact text that includes dynamic data (dates, counts, prices)
• Don't navigate to more than 3-4 pages in a single check
• Don't fill forms with real credentials - use test accounts or environment variables
• Don't use page.evaluate() for assertions - use Playwright's built-in matchers
• Don't use React Testing Library methods (getByDisplayValue, queryByText, findByRole, getAllByTestId, etc.) - these are NOT Playwright APIs
• Don't use getBySelector(), getByCssSelector(), or getByXPath() - use page.locator() or page.getByRole()

script templates

login flow monitoring

import { test, expect } from "@playwright/test";

test("login flow works", async ({ page }) => {
  await page.goto("https://YOUR_APP_URL/login", { waitUntil: "networkidle" });

  // Fill credentials
  await page.getByTestId("email-input").fill("monitor@example.com");
  await page.getByTestId("password-input").fill("test-password");
  await page.getByTestId("login-button").click();

  // Verify successful login
  await expect(page.getByTestId("dashboard")).toBeVisible({ timeout: 10000 });
  await expect(page).toHaveURL(/dashboard/);
});

page load monitoring

import { test, expect } from "@playwright/test";

test("homepage loads correctly", async ({ page }) => {
  const response = await page.goto("https://YOUR_APP_URL", { waitUntil: "networkidle" });

  // Verify page loaded
  expect(response?.status()).toBeLessThan(400);
  await expect(page.getByRole("heading", { level: 1 })).toBeVisible();

  // Verify key content is present
  await expect(page.getByTestId("hero-section")).toBeVisible();
  await expect(page.getByTestId("nav-menu")).toBeVisible();
});

form submission monitoring

import { test, expect } from "@playwright/test";

test("contact form submits successfully", async ({ page }) => {
  await page.goto("https://YOUR_APP_URL/contact", { waitUntil: "networkidle" });

  // Fill form
  await page.getByTestId("name-input").fill("Monitor Bot");
  await page.getByTestId("email-input").fill("monitor@example.com");
  await page.getByTestId("message-input").fill("Automated monitoring check");
  await page.getByTestId("submit-button").click();

  // Verify submission
  await expect(page.getByTestId("success-message")).toBeVisible({ timeout: 10000 });
});

API health check

API checks use a different approach - no Playwright script needed. Use the CLI directly:

supaguard checks create --type api \
  --name "API Health" \
  --url "https://api.example.com/health" \
  --method GET \
  --assert-status 200 \
  --assert-response-time 5000 \
  --locations eastus,northeurope \
  --cron "*/5 * * * *" \
  --json

allowed npm packages in scripts

Scripts can import these packages (they're available in the runner):

• @playwright/test (always available)
• @faker-js/faker / faker - for generating test data
• dayjs / date-fns - for date manipulation
• lodash / lodash-es - for utility functions
• uuid - for generating UUIDs
• zod - for schema validation