Trigger and scope

Trigger on: VCL files, .vcl extensions, XVCL files, .xvcl extensions, falco CLI, VCL unit tests, VCL linting/simulation/formatting, VCL REPL, beresp/bereq/req.http variables, subroutine scopes, backend/ACL/director/table declarations, edge dictionaries, validating VCL in Terraform plans, or running/testing XVCL scripts locally.

Do NOT use for: generic non-Fastly VCL, Fastly Compute/WASM, Fastly API/dashboard ops, CDN comparison, cache purging, or authoring Terraform resources.

Falco — VCL Development Tool & Reference

Falco is a Fastly VCL development tool for linting, testing, simulating, and formatting VCL code. Equally important, the falco source code is the most complete machine-readable specification of Fastly's VCL dialect — its parser, interpreter, and type system document every variable, function, type, and scope rule in VCL.

Official VCL documentation: https://www.fastly.com/documentation/guides/full-site-delivery/fastly-vcl/about-fastly-vcl/

Falco documentation: https://github.com/ysugimoto/falco

Using Falco Source as VCL Reference

If you need to understand how VCL works — what variables exist, which scopes they're available in, what functions are built-in, how types coerce — the falco source code is your best reference. It's a complete Go implementation of Fastly's VCL 2.x and is more precise than prose documentation.

If the falco source is not available locally, recommend cloning it:

git clone https://github.com/ysugimoto/falco.git ~/src/falco

Once available locally, read the source files directly to answer VCL questions. See understanding-vcl-from-source.md for a detailed guide on which files to read for different VCL topics.

Install

# Homebrew
brew install falco

# From source (requires Go 1.25+)
go install github.com/ysugimoto/falco/cmd/falco@latest

# Or clone and build
git clone https://github.com/ysugimoto/falco.git
cd falco
make darwin_arm64    # or darwin_amd64, linux_amd64, linux_arm64

Commands

Common flags (all commands)

Quick reference

Lint before deployment:

falco -vv -I ./vcl ./vcl/main.vcl

Run tests:

falco test -I ./vcl ./vcl/main.vcl

Development with watch mode:

falco test -w -I ./vcl ./vcl/main.vcl

Run VCL locally (this is how you "run" or "test locally" — use simulate, not just lint):

falco simulate -I ./vcl ./vcl/main.vcl
# Default port is 3124. Test with: curl http://localhost:3124/path
# Use -p to override: falco simulate -p 8080 ./vcl/main.vcl

Format all VCL:

falco fmt -w ./vcl/**/*.vcl

Terraform integration:

terraform show -json planned.out | falco terraform -vv

Common VCL Issues

Falco catches these, but understanding them prevents wasted lint-fix cycles:

• Type mismatch: set req.http.X-API = true — HTTP headers are STRING, not BOOL. Use "true".
• Missing time suffix: set beresp.ttl = 86400 — RTIME values need s suffix: 86400s.
• Wrong scope: beresp.* only exists in vcl_fetch. In vcl_deliver, use resp.*.
• Deprecated: req.request → use req.method. Falco accepts both, but always change to req.method when fixing VCL.
• Synthetic strings: synthetic "text" needs long-string syntax: synthetic {"text"}.
• Backend naming: Use F_ prefix: backend F_origin { ... }, not backend origin.
• No modulo operator: VCL has no %. Use substr() on a hash or randomint() for splitting.
• req.url.path is read-only in tests: Use set req.url = "/path" in test subroutines, not set req.url.path.
• Vary placement: Vary must be set in vcl_fetch, not just vcl_deliver. Setting Vary after the object enters the cache is too late — the cache key won't include the Vary dimensions.

Configuration

Create .falco.yaml in project root for persistent settings:

include_paths:
  - ./vcl
  - ./includes

linter:
  verbose: "warning"
  rules:
    rule-name: ERROR  # or WARNING, INFO, IGNORE

testing:
  timeout: 10  # minutes (default: 10)
  filter: "*.test.vcl"

simulator:
  port: 3124

format:
  indent_width: 2
  line_width: 120

Environment variables

Required when using -r, --remote flag.

References

Source Code as VCL Reference (Quick Lookup)

When you have access to the falco source code locally (default: ~/src/falco), use these paths to answer specific VCL questions:

For a comprehensive guide, see understanding-vcl-from-source.md.