falco

Files (9)

• SKILL.md
• formatting-vcl.md · references/
• linting-vcl.md · references/
• simulating-vcl.md · references/
• terraform-vcl.md · references/
• testing-vcl.md · references/
• understanding-vcl-from-source.md · references/
• vcl-console.md · references/
• vcl-statistics.md · references/

SKILL.md (first lines)

## 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:
```bash
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](references/understanding-vcl-from-source.md) for a detailed guide on which files to read for different VCL topics.

## Install

```bash
# 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

| Command           | Description                      |
| ----------------- | -------------------------------- |
| `falco [lint]`    | Lint VCL files (default command) |
| `falco test`      | Run VCL unit tests               |
| `falco simulate`  | Start local simulator server     |
| `falco fmt`       | Format VCL files                 |
| `falco stats`     | Show VCL code statistics         |
| `falco console`   | Interactive VCL REPL             |
| `falco terraform` | Lint VCL from Terraform plans    |
| `falco dap`       | Debug Adapter Protocol server    |

## Common flags (all commands)

| Flag                 | Description                      |
| -------------------- | -------------------------------- |
| `-I, --include_path` | Add include path for VCL imports |
| `-h, --help`         | Show help                        |
| `-V, --version`      | Show version                     |
| `-r, --remote`       | Fetch snippets from Fastly API   |
| `--refresh`          | Refresh remote snippet cache     |

## Quick reference

**Lint before deployment:**
```bash
falco -vv -I ./vcl ./vcl/main.vcl
```

**Run tests:**
```bash
falco test -I ./vcl ./vcl/main.vcl
```

**Development with watch mode:**
```bash
falco test -w -I ./vcl ./vcl/main.vcl
```

**Run VCL locally** (this is how you "run" or "test locally" — use `simulate`, not just `lint`):
```bash
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:**
```bash
falco fmt -w ./vcl/**/*.vcl
```

**Terraform integration:**
```bash
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:

```yaml
include_paths:
  - ./vcl
  - ./includes

From fastly/fastly-agent-toolkit, MIT.

More from fastly/fastly-agent-toolkit