falco

Name: falco
Author: fastly

28stars5forks

How to install falco?

fastly/fastly-agent-toolkit/falco

$npx -y skills add fastly/fastly-agent-toolkit --skill falco

Installs into the current project.

Summary

Lints, tests, simulates, and formats Fastly VCL code using the falco tool. Also serves as the authoritative VCL reference via the falco Go source, which implements Fastly's full VCL dialect. Use when validating VCL syntax, running VCL linting, testing VCL locally, simulating VCL

Files · 1

View on GitHub

SKILL.md

1	## Trigger and scope
2
3	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.
4
5	Do NOT use for: generic non-Fastly VCL, Fastly Compute/WASM, Fastly API/dashboard ops, CDN comparison, cache purging, or authoring Terraform resources.
6
7	# Falco — VCL Development Tool & Reference
8
9	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.
10
11	Official VCL documentation: https://www.fastly.com/documentation/guides/full-site-delivery/fastly-vcl/about-fastly-vcl/
12
13	Falco documentation: https://github.com/ysugimoto/falco
14
15	## Using Falco Source as VCL Reference
16
17	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.
18
19	If the falco source is not available locally, recommend cloning it:
20	```bash
21	git clone https://github.com/ysugimoto/falco.git ~/src/falco
22	```
23
24	Once available locally, read the source files directly to answer VCL questions. See [understanding-vcl-from-source.md](references/understanding-vcl-from-source.md) for a detailed guide on which files to read for different VCL topics.
25
26	## Install
27
28	```bash
29	# Homebrew
30	brew install falco
31
32	# From source (requires Go 1.25+)
33	go install github.com/ysugimoto/falco/cmd/falco@latest
34
35	# Or clone and build
36	git clone https://github.com/ysugimoto/falco.git
37	cd falco
38	make darwin_arm64 # or darwin_amd64, linux_amd64, linux_arm64
39	```
40
41	## Commands
42
43	\| Command \| Description \|
44	\| ----------------- \| -------------------------------- \|
45	\| `falco [lint]` \| Lint VCL files (default command) \|
46	\| `falco test` \| Run VCL unit tests \|
47	\| `falco simulate` \| Start local simulator server \|
48	\| `falco fmt` \| Format VCL files \|
49	\| `falco stats` \| Show VCL code statistics \|
50	\| `falco console` \| Interactive VCL REPL \|
51	\| `falco terraform` \| Lint VCL from Terraform plans \|
52	\| `falco dap` \| Debug Adapter Protocol server \|
53
54	## Common flags (all commands)
55
56	\| Flag \| Description \|
57	\| -------------------- \| -------------------------------- \|
58	\| `-I, --include_path` \| Add include path for VCL imports \|
59	\| `-h, --help` \| Show help \|
60	\| `-V, --version` \| Show version \|
61	\| `-r, --remote` \| Fetch snippets from Fastly API \|
62	\| `--refresh` \| Refresh remote snippet cache \|
63
64	## Quick reference
65
66	Lint before deployment:
67	```bash
68	falco -vv -I ./vcl ./vcl/main.vcl
69	```
70
71	Run tests:
72	```bash
73	falco test -I ./vcl ./vcl/main.vcl
74	```
75
76	Development with watch mode:
77	```bash
78	falco test -w -I ./vcl ./vcl/main.vcl
79	```
80
81	Run VCL locally (this is how you "run" or "test locally" — use `simulate`, not just `lint`):
82	```bash
83	falco simulate -I ./vcl ./vcl/main.vcl
84	# Default port is 3124. Test with: curl http://localhost:3124/path
85	# Use -p to override: falco simulate -p 8080 ./vcl/main.vcl
86	```
87
88	Format all VCL:
89	```bash
90	falco fmt -w ./vcl/*/.vcl
91	```
92
93	Terraform integration:
94	```bash
95	terraform show -json planned.out \| falco terraform -vv
96	```
97
98	## Common VCL Issues
99
100	Falco catches these, but understanding them prevents wasted lint-fix cycles:
101
102	- Type mismatch: `set req.http.X-API = true` — HTTP headers are STRING, not BOOL. Use `"true"`.
103	- Missing time suffix: `set beresp.ttl = 86400` — RTIME values need `s` suffix: `86400s`.
104	- Wrong scope: `beresp.` only exists in `vcl_fetch`. In `vcl_deliver`, use `resp.`.
105	- Deprecated: `req.request` → use `req.method`. Falco accepts both, but a

People who liked this also viewed

6 picks

Type

falco

28stars5forks

View on GitHub

How to install falco?

fastly/fastly-agent-toolkit/falco

$npx -y skills add fastly/fastly-agent-toolkit --skill falco

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	## Trigger and scope
2
3	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.
4
5	Do NOT use for: generic non-Fastly VCL, Fastly Compute/WASM, Fastly API/dashboard ops, CDN comparison, cache purging, or authoring Terraform resources.
6
7	# Falco — VCL Development Tool & Reference
8
9	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.
10
11	Official VCL documentation: https://www.fastly.com/documentation/guides/full-site-delivery/fastly-vcl/about-fastly-vcl/
12
13	Falco documentation: https://github.com/ysugimoto/falco
14
15	## Using Falco Source as VCL Reference
16
17	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.
18
19	If the falco source is not available locally, recommend cloning it:
20	```bash
21	git clone https://github.com/ysugimoto/falco.git ~/src/falco
22	```
23
24	Once available locally, read the source files directly to answer VCL questions. See [understanding-vcl-from-source.md](references/understanding-vcl-from-source.md) for a detailed guide on which files to read for different VCL topics.
25
26	## Install
27
28	```bash
29	# Homebrew
30	brew install falco
31
32	# From source (requires Go 1.25+)
33	go install github.com/ysugimoto/falco/cmd/falco@latest
34
35	# Or clone and build
36	git clone https://github.com/ysugimoto/falco.git
37	cd falco
38	make darwin_arm64 # or darwin_amd64, linux_amd64, linux_arm64
39	```
40
41	## Commands
42
43	\| Command \| Description \|
44	\| ----------------- \| -------------------------------- \|
45	\| `falco [lint]` \| Lint VCL files (default command) \|
46	\| `falco test` \| Run VCL unit tests \|
47	\| `falco simulate` \| Start local simulator server \|
48	\| `falco fmt` \| Format VCL files \|
49	\| `falco stats` \| Show VCL code statistics \|
50	\| `falco console` \| Interactive VCL REPL \|
51	\| `falco terraform` \| Lint VCL from Terraform plans \|
52	\| `falco dap` \| Debug Adapter Protocol server \|
53
54	## Common flags (all commands)
55
56	\| Flag \| Description \|
57	\| -------------------- \| -------------------------------- \|
58	\| `-I, --include_path` \| Add include path for VCL imports \|
59	\| `-h, --help` \| Show help \|
60	\| `-V, --version` \| Show version \|
61	\| `-r, --remote` \| Fetch snippets from Fastly API \|
62	\| `--refresh` \| Refresh remote snippet cache \|
63
64	## Quick reference
65
66	Lint before deployment:
67	```bash
68	falco -vv -I ./vcl ./vcl/main.vcl
69	```
70
71	Run tests:
72	```bash
73	falco test -I ./vcl ./vcl/main.vcl
74	```
75
76	Development with watch mode:
77	```bash
78	falco test -w -I ./vcl ./vcl/main.vcl
79	```
80
81	Run VCL locally (this is how you "run" or "test locally" — use `simulate`, not just `lint`):
82	```bash
83	falco simulate -I ./vcl ./vcl/main.vcl
84	# Default port is 3124. Test with: curl http://localhost:3124/path
85	# Use -p to override: falco simulate -p 8080 ./vcl/main.vcl
86	```
87
88	Format all VCL:
89	```bash
90	falco fmt -w ./vcl/*/.vcl
91	```
92
93	Terraform integration:
94	```bash
95	terraform show -json planned.out \| falco terraform -vv
96	```
97
98	## Common VCL Issues
99
100	Falco catches these, but understanding them prevents wasted lint-fix cycles:
101
102	- Type mismatch: `set req.http.X-API = true` — HTTP headers are STRING, not BOOL. Use `"true"`.
103	- Missing time suffix: `set beresp.ttl = 86400` — RTIME values need `s` suffix: `86400s`.
104	- Wrong scope: `beresp.` only exists in `vcl_fetch`. In `vcl_deliver`, use `resp.`.
105	- Deprecated: `req.request` → use `req.method`. Falco accepts both, but a

People who liked this also viewed

6 picks

Type