vwaffle Documentation

Pages

1. OverviewWhat vwaffle exposes, who should run it, the vwaffle binary entry point, and the shortest pull / plan / apply path.
2. InstallationNode >=18, global npm install, npx and bunx one-shot invocation, and the published dist/index.js binary.
3. QuickstartSet VERCEL_TOKEN, scaffold or pull firewall.config.json, preview with plan, then apply --yes, including the first success signal.
4. Desired vs live configHow the local desired JSON relates to the active Vercel Firewall config fetched and written by the API client.
5. Project and team contextHow resolveContext selects VERCEL_TOKEN, project ID, and team ID from flags, environment variables, and .vercel/project.json.
6. Secret interpolationHow ${VAR_NAME} placeholders are expanded, when missing variables drop rules versus fail apply, and how values are redacted in CLI output.
7. Plan and apply lifecycleplan versus apply, --check drift exit codes, --dry-run payload print, and the --yes confirmation required to PUT.
8. Firewall rule modelRepo-backed shape of firewallEnabled, managedRules, rules, conditionGroup, mitigate actions, and ips entries sent to Vercel.
9. Scaffold and pull a configWrite a starter firewall.config.json with init, or fetch the live config with pull and --output.
10. Author firewall rulesEdit the desired JSON for custom rules, OWASP managed rules, IP denylists, and environment placeholders without committing secrets.
11. Preview and apply changesDiff live versus desired with plan, inspect a redacted payload with apply --dry-run, then PUT with apply --yes.
12. Detect drift in CIRun plan --check so a dashboard edit that diverges from the versioned file fails the build.
13. Apply from CIPromote firewall.config.json as source of truth by running apply --yes on merge with project, team, and token inputs.
14. CLI referencevwaffle commands init, pull, plan, apply, and help, plus flags --config, --output, --check, --dry-run, --yes, --project, and --team.
15. Configuration referenceDesired-file path default, JSON body accepted by PUT /v1/security/firewall/config, and loadDesiredConfig interpolation rules.
16. Environment variablesVERCEL_TOKEN, VERCEL_PROJECT_ID, VERCEL_TEAM_ID, and arbitrary ${VAR_NAME} values interpolated into string fields.
17. Firewall API clientresolveContext, getActiveConfig, putConfig, request, and requestUrl used to read and write the Vercel Firewall config.
18. Diff outputHow diff, diffLines, lcsMatrix, and withContext render live-versus-desired changes, including redacted secret values.
19. Authentication and context errorsMissing VERCEL_TOKEN, unresolved project or team IDs, and failed Firewall API requests from resolveContext and request.
20. Interpolation and check failuresUnset ${VAR_NAME} behavior on plan versus apply, rules skipped by removeRulesWithMissingEnv, and plan --check exit 1 on drift.
21. Build and testBun scripts for typecheck, bun test, bun build of src/index.ts to dist, and the local bun run src/index.ts dev path.
22. ContributingprepublishOnly gates, Node engine, Apache-2.0 package metadata, and the files published as the vwaffle CLI.