# vwaffle Documentation

> CLI for treating Vercel Firewall, WAF, and bot-protection configuration as versioned JSON. Covers install, project context, secret interpolation, pull/plan/apply, the Firewall API client, and CI drift checks.

This is a Grok-Wiki source-grounded repository documentation set. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown docs](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581.md)
- [Human interactive docs](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581)
- [GitHub repository](https://github.com/jaredpalmer/vwaffle)

## Repository

- Repository: jaredpalmer/vwaffle

- Generated: 2026-08-13T01:30:01.592Z
- Updated: 2026-08-13T01:33:20.954Z
- Runtime: Grok CLI
- Format: Documentation
- Pages: 22

## Pages

- [Overview](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/01-overview.md): What vwaffle exposes, who should run it, the vwaffle binary entry point, and the shortest pull / plan / apply path.
- [Installation](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/02-installation.md): Node >=18, global npm install, npx and bunx one-shot invocation, and the published dist/index.js binary.
- [Quickstart](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/03-quickstart.md): Set VERCEL_TOKEN, scaffold or pull firewall.config.json, preview with plan, then apply --yes, including the first success signal.
- [Desired vs live config](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/04-desired-vs-live-config.md): How the local desired JSON relates to the active Vercel Firewall config fetched and written by the API client.
- [Project and team context](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/05-project-and-team-context.md): How resolveContext selects VERCEL_TOKEN, project ID, and team ID from flags, environment variables, and .vercel/project.json.
- [Secret interpolation](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/06-secret-interpolation.md): How ${VAR_NAME} placeholders are expanded, when missing variables drop rules versus fail apply, and how values are redacted in CLI output.
- [Plan and apply lifecycle](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/07-plan-and-apply-lifecycle.md): plan versus apply, --check drift exit codes, --dry-run payload print, and the --yes confirmation required to PUT.
- [Firewall rule model](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/08-firewall-rule-model.md): Repo-backed shape of firewallEnabled, managedRules, rules, conditionGroup, mitigate actions, and ips entries sent to Vercel.
- [Scaffold and pull a config](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/09-scaffold-and-pull-a-config.md): Write a starter firewall.config.json with init, or fetch the live config with pull and --output.
- [Author firewall rules](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/10-author-firewall-rules.md): Edit the desired JSON for custom rules, OWASP managed rules, IP denylists, and environment placeholders without committing secrets.
- [Preview and apply changes](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/11-preview-and-apply-changes.md): Diff live versus desired with plan, inspect a redacted payload with apply --dry-run, then PUT with apply --yes.
- [Detect drift in CI](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/12-detect-drift-in-ci.md): Run plan --check so a dashboard edit that diverges from the versioned file fails the build.
- [Apply from CI](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/13-apply-from-ci.md): Promote firewall.config.json as source of truth by running apply --yes on merge with project, team, and token inputs.
- [CLI reference](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/14-cli-reference.md): vwaffle commands init, pull, plan, apply, and help, plus flags --config, --output, --check, --dry-run, --yes, --project, and --team.
- [Configuration reference](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/15-configuration-reference.md): Desired-file path default, JSON body accepted by PUT /v1/security/firewall/config, and loadDesiredConfig interpolation rules.
- [Environment variables](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/16-environment-variables.md): VERCEL_TOKEN, VERCEL_PROJECT_ID, VERCEL_TEAM_ID, and arbitrary ${VAR_NAME} values interpolated into string fields.
- [Firewall API client](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/17-firewall-api-client.md): resolveContext, getActiveConfig, putConfig, request, and requestUrl used to read and write the Vercel Firewall config.
- [Diff output](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/18-diff-output.md): How diff, diffLines, lcsMatrix, and withContext render live-versus-desired changes, including redacted secret values.
- [Authentication and context errors](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/19-authentication-and-context-errors.md): Missing VERCEL_TOKEN, unresolved project or team IDs, and failed Firewall API requests from resolveContext and request.
- [Interpolation and check failures](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/20-interpolation-and-check-failures.md): Unset ${VAR_NAME} behavior on plan versus apply, rules skipped by removeRulesWithMissingEnv, and plan --check exit 1 on drift.
- [Build and test](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/21-build-and-test.md): Bun scripts for typecheck, bun test, bun build of src/index.ts to dist, and the local bun run src/index.ts dev path.
- [Contributing](https://grok-wiki.com/public/docs/jaredpalmer-vwaffle-7983cb893581/pages/22-contributing.md): prepublishOnly gates, Node engine, Apache-2.0 package metadata, and the files published as the vwaffle CLI.

## Source Files

- `package.json`
- `README.md`
- `src/api.ts`
- `src/config.test.ts`
- `src/config.ts`
- `src/diff.ts`
- `src/index.ts`
- `src/types.ts`