CLI reference

All commands accept --stage <name>. If omitted, wisp reads the WISP_STAGE environment variable, then falls back to "dev". See per-branch stages if you want one stage per git branch.

Every command also accepts --help; wisp --version prints the installed version.

wisp synth

wisp synth [--stage <name>]

Analyses your project and writes the synthesized CloudFormation to .wisp/cloudformation.json (and, for larger apps, .wisp/shards/*.json — see Stack sharding) without touching AWS. Blocks with diagnostics if analysis fails, or if the always-on denylist catches something.

✓ Wrote .wisp/cloudformation.json and .wisp/graph.json

wisp deploy

wisp deploy [stage]

Runs synth, bundles every function, uploads artifacts, and deploys via a CloudFormation change set. Returns 202-style quickly for the change set creation, then reports the final stack status once it settles.

✓ Stack deployed: CREATE_COMPLETE
  MainInvokeUrl: https://abc123.execute-api.eu-north-1.amazonaws.com

wisp graph

wisp graph [--json]

Prints the resource graph — every resource wisp found, and the edges between functions and the resources they touch. --json for machine-readable output; useful for scripting or debugging why a permission wasn't derived the way you expected.

wisp iam

wisp iam

Prints a table of every function and its exact derived IAM permissions. See IAM derivation.

wisp estimate

wisp estimate

Prints your idle cost floor (should be $0.00, unless you've explicitly allowed something past the denylist) plus a projected cost at 1M requests/month, broken down by resource kind.

wisp doctor

wisp doctor

Verifies your environment is ready to deploy: wisp.config.ts is valid, you're running Bun >= 1.3, the configured region is a real AWS region, AWS credentials resolve via STS, and the artifact bucket is in the expected bootstrap state. Exits non-zero if any check fails.

✓ wisp 0.1.0 — environment summary
  ✓ Project — wisp.config.ts valid (app "hello-world", region eu-north-1)
  ✓ Bun — v1.3.14
  ✓ Region — eu-north-1
  ✓ AWS credentials — valid for account 123456789012 in eu-north-1
  ✓ Bootstrap — artifact bucket "wisp-artifacts-123456789012-eu-north-1" exists

The artifact bucket check is read-only: a missing bucket is reported as a warning (the next wisp deploy creates it automatically), not a failure.

wisp invoke

wisp invoke <exportName> [--event <file.json>]

Runs one function locally against real deployed AWS resources. See Local Development.

wisp dev

wisp dev

Bridges real traffic to your local machine with hot reload. See Local Development.

wisp destroy

wisp destroy [stage]

Tears down the stack for the given stage. If the stage name contains prod (case-insensitive), wisp requires you to type the exact stage name back as confirmation before deleting anything:

Type the stage name "prod" to confirm deletion: