Getting started

CLI and SDK

PreFlight exposes a maintained npm SDK for runtime signals and typed automation, alongside a REST API, MCP server, and shell-friendly CI patterns. This page covers each interface and when to use it.

There is no standalone CLI binary. Instead, PreFlight provides HTTP endpoints and an MCP server that work with standard tools — curl, fetch, GitHub Actions, and AI hosts like Cursor and Claude Desktop.

Interface comparison

| Interface | Transport | Best for | Auth | | --- | --- | --- | --- | | npm SDK | npm | RUM, Shield, Threat Signals, typed server and CI calls | Project client/server keys or `pf_live_*` key | | REST API v1 | HTTPS | CI pipelines, status bots, custom dashboards | Bearer `pf_live_*` key | | MCP Server | stdio (local) | AI agents in Cursor, Claude Desktop, Windsurf | `PREFLIGHT_API_KEY` env var | | Dashboard | Browser | Human operators, configuration, visual debugging | Supabase session cookie | | Cron endpoint | HTTPS (server-to-server) | Scheduled monitoring and sampling | Bearer `CRON_SECRET` |

npm SDK

npm install @getpreflight/sdk

Use @getpreflight/sdk/next for the Next.js component, /browser for framework-neutral setup, /server for privacy-safe Threat Signals, and /api for typed automation. See Install the SDK for supported examples and the fixed coding-agent prompt.

REST API quick reference

Base URL: https://getpreflight.dev/api/v1

| Action | Method | Endpoint | | --- | --- | --- | | List projects | GET | `/projects` | | Trigger checks | POST | `/projects/:id/checks` | | Poll a run | GET | `/projects/:id/checks/:runId` | | Project status | GET | `/projects/:id/status` | | release rule | GET | `/projects/:id/deploy-gate` | | Incidents | GET | `/projects/:id/incidents` | | Uptime SLA | GET | `/projects/:id/uptime` | | Activity log | GET | `/projects/:id/activity` | | Launch report | GET | `/projects/:id/report` | | Database Change Check | GET | `/projects/:id/schema-sync` |

curl example: trigger a check

curl -X POST \
  -H "Authorization: Bearer pf_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-$(date +%Y%m%d-%H%M%S)" \
  https://getpreflight.dev/api/v1/projects/YOUR_PROJECT_UUID/checks

curl example: query the release rule

response=$(curl -sS -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $PREFLIGHT_API_KEY" \
  "https://getpreflight.dev/api/v1/projects/$PROJECT_ID/deploy-gate?mode=strict")

if [ "$response" != "200" ]; then
  echo "Deploy blocked"
  exit 1
fi

MCP Server

The MCP server wraps the REST API into tool calls that AI agents understand natively. It runs locally via stdio transport.

Install and run

# From the PreFlight repository root
npm install
npm run mcp -- --api-key pf_live_... --project-id YOUR_UUID

Or configure environment variables:

PREFLIGHT_API_KEY=pf_live_...
PREFLIGHT_PROJECT_ID=550e8400-e29b-41d4-a716-446655440000
PREFLIGHT_API_URL=https://getpreflight.dev

Available MCP tools

| Tool | Description | | --- | --- | | `list_projects` | List all accessible projects | | `run_checks` | Run the full check suite | | `get_status` | Overall health, uptime, and provider status | | `get_deploy_gate` | Evaluate release readiness | | `get_incidents` | Open incidents and recent failures | | `get_uptime` | 24h/7d/30d uptime percentages | | `get_activity` | Recent audit events |

See the dedicated MCP server guide for host configuration examples.

CI integration patterns

GitHub Actions

jobs:
  preflight-gate:
    runs-on: ubuntu-latest
    steps:
      - name: Run PreFlight checks
        run: |
          curl -X POST \
            -H "Authorization: Bearer ${{ secrets.PREFLIGHT_API_KEY }}" \
            -H "Idempotency-Key: ${{ github.run_id }}" \
            https://getpreflight.dev/api/v1/projects/${{ vars.PROJECT_ID }}/checks

      - name: Query release rule
        run: |
          code=$(curl -sS -o gate.json -w "%{http_code}" \
            -H "Authorization: Bearer ${{ secrets.PREFLIGHT_API_KEY }}" \
            "https://getpreflight.dev/api/v1/projects/${{ vars.PROJECT_ID }}/deploy-gate?mode=strict")
          cat gate.json
          if [ "$code" != "200" ]; then
            echo "::error::release rule blocked the release"
            exit 1
          fi

GitLab CI

preflight-gate:
  stage: deploy
  script:
    - |
      code=$(curl -sS -o gate.json -w "%{http_code}" \
        -H "Authorization: Bearer $PREFLIGHT_API_KEY" \
        "$PREFLIGHT_URL/api/v1/projects/$PROJECT_ID/deploy-gate?mode=strict")
      cat gate.json
      if [ "$code" != "200" ]; then exit 1; fi
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Vercel deploy hook

Run the gate check before vercel deploy --prod:

#!/bin/bash
set -e

# Trigger fresh check
curl -sS -X POST \
  -H "Authorization: Bearer $PREFLIGHT_API_KEY" \
  -H "Idempotency-Key: vercel-$(date +%s)" \
  "$PREFLIGHT_URL/api/v1/projects/$PROJECT_ID/checks"

# Wait for check to complete (simple polling)
sleep 10

# Evaluate gate
code=$(curl -sS -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $PREFLIGHT_API_KEY" \
  "$PREFLIGHT_URL/api/v1/projects/$PROJECT_ID/deploy-gate?mode=strict")

if [ "$code" = "200" ]; then
  vercel deploy --prod
else
  echo "PreFlight gate blocked deployment"
  exit 1
fi

SDK design principles

| Principle | Implementation | | --- | --- | | HTTP-first | No proprietary binary; any HTTP client works | | Idempotent writes | `Idempotency-Key` header prevents duplicate check runs | | Deterministic responses | `status`, `counts`, and probe rows are always derived from stored evidence | | Stable identifiers | Project UUIDs, probe keys, and error codes are stable across versions | | Fail-safe defaults | Missing optional fields return sensible defaults, not errors |

Environment variables reference

| Variable | Used by | Purpose | | --- | --- | --- | | `PREFLIGHT_API_KEY` | REST API, MCP server | Bearer authentication | | `PREFLIGHT_PROJECT_ID` | MCP server, CI scripts | Default project target | | `PREFLIGHT_API_URL` | MCP server, self-hosted | Override base URL (defaults to production) | | `CRON_SECRET` | Scheduler | Cron endpoint authentication | | `SUPABASE_SERVICE_ROLE_KEY` | Server | Database access for cron and API | | `ENCRYPTION_KEY` | Server | AES-256-GCM for credential vault | | `RESEND_API_KEY` | Server | Email alert delivery | | `CEREBRAS_API_KEY` | Server | Optional AI diagnosis | | `GROQ_API_KEY` | Server | Primary AI diagnosis provider; falls back to Cerebras, then Mistral | PreFlight does not require a global CLI install. The MCP server runs from the repository with npm run mcp, and the REST API works with any HTTP client. This keeps your CI environment clean and avoids version drift.

<RelatedLinks links={[ { href: "/docs/api/overview", title: "API overview", description: "Full resource catalog and response shapes." }, { href: "/docs/api/authentication", title: "API authentication", description: "Key creation, scopes, and rate limits." }, { href: "/docs/api/mcp-server", title: "MCP server", description: "Detailed setup for Cursor, Claude Desktop, and other hosts." }, { href: "/docs/guides/deploy-gates", title: "Release Rules", description: "Turn API calls into CI release blockers." }, ]} />