Falco

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 [blocked] for a detailed guide on which files to read for different VCL topics.

Install

# Homebrewbrew install falco
# From source (requires Go 1.25+)go install github.com/ysugimoto/falco/cmd/falco@latest
# Or clone and buildgit clone https://github.com/ysugimoto/falco.gitcd falcomake 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.

Configure API credentials locally, outside chat. Never ask for an API key in a conversation or print its value.

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 [blocked].