/Getting Started
v1.2CLI and SDK
Automation interfaces — REST API, MCP server, and CI integration patterns.
Getting started
CLI and SDK
PreFlight exposes automation through a REST API, an MCP server for AI agents, and shell-friendly patterns for CI pipelines. 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 |
|---|---|---|---|
| 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 |
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 |
| Deploy gate | 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 |
| Schema sync | 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 deploy gate
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 |
preflight_trigger_checks | Run the full check suite |
get_sentinel_status | Overall health, uptime, and provider status |
get_deploy_gate_status | Evaluate release readiness |
get_active_incidents | Open incidents and recent failures |
get_uptime_sla | 24h/7d/30d uptime percentages |
get_project_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 deploy gate
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::Deploy gate 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 |
No global install needed
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.