Deploying and validating
The loop around a Driftfile: check it offline, fold your build into the deploy, then plan and apply it and read whatever it says back.
Working on a Driftfile
drift file answers questions about a Driftfile without touching the network. It's the fast loop: fix, lint, repeat, and only then plan.
| Command | What it answers |
|---|---|
drift file lint | Is this file valid? It compiles and validates exactly as drift plan would, without an account, a network or the values of its secrets, and exits non-zero, so it can gate CI. It also checks that each handler exists in its backend's source. |
drift file resolve --env staging | What does this file compile to for staging? Every booking, size and limit, and the slice it applies to. Without --env it resolves the file's own slice. |
drift file explain atomic.backend.function | What does the format say? It describes a block or an attribute of the format itself, not your file. |
drift file fmt --write | The file in HCL's canonical layout: two-space indentation and aligned =. Comments, blank lines and the order of everything are kept; only whitespace changes. |
drift file new | A starter Driftfile in this directory. |
drift file run | Builds and runs the project locally in Docker, with --port, --persist, --no-env-file, and an environment name. drift file logs reads its logs and drift file stop stops it. |
drift file test | Runs the project locally, waits for it to be healthy, runs your test blocks, and always tears it down. |
drift file benchmark | Reports what each Function and Worker measured and the size it should book. drift size writes those sizes into the file. |
On a valid file, drift file lint prints Driftfile is valid with the slice's name. Without --write, drift file fmt prints the formatted file and changes nothing; with it, the file is rewritten in place.
explain describes the format; resolve describes one file. drift file explain lists every block a Driftfile can hold, drift file explain atomic.backend.function.memory describes one attribute, drift file explain slice.limits lists the limits, and --recursive prints everything under the path. drift file resolve takes your file, with an environment if you name one, and prints the shape it provisions. Neither prints the value of a secret: a secret, an API key and a site password are references, and resolve lists them by the name of the variable they are read from. Neither prints a price either; the price is the platform's quote, and drift plan shows it.
Hooks: pre/post-deploy commands
Fold the build-and-verify ceremony into the deploy so it stays one command. A hook block is labelled with when it runs and names one command; write one block per command. Commands run locally, in order, through the shell from the project root, and a non-zero exit aborts.
slice "web" {}
atomic {
backend "default" {
function "GET /ping" {
handler = "GetPing"
memory = "32MiB"
}
}
}
# before anything ships, typically a build
hook "pre_deploy" {
run = "npm --prefix web run build"
}
# after the slice is live, typically a smoke test
hook "post_deploy" {
run = "./scripts/smoke.sh"
}pre_deploy runs at the start of drift apply, before the file is checked, so a build it produces can be a folder the Driftfile names. post_deploy runs once the slice is live. A failed post_deploy leaves the slice live but exits non-zero, so you and CI see it. drift plan runs neither.
Hooks are lifecycle commands, not a pipeline engine: no test stages, matrices, parallelism, or remote execution.
Tests
A test block names a command that drift file test runs against the project running locally. The local instance's address comes in as DRIFT_TEST_URL, so a test points at it without a fixed port, and the instance is torn down whether the tests pass or not.
slice "web" {}
atomic {
backend "default" {
function "GET /ping" {
handler = "GetPing"
memory = "32MiB"
}
}
}
test "e2e" {
run = "npx playwright test"
}
test "api" {
run = "./scripts/api-test.sh"
}drift file test staging runs the same blocks against the staging environment's local build. A file with no test block makes drift file test say so and show the block to add.
Reading an error
The CLI validates the whole Driftfile before any network call. Malformed values, missing files and folders, missing sizes, secrets written as literals, and unset references are reported together, so you fix everything in one pass. Every error carries its position in the file, Driftfile:line:column, and they are listed top to bottom:
Driftfile
3 validation errors:
- Driftfile:8:15: Not a size: function "POST /items": memory "64MB" is not a size: write a whole number of KiB, MiB or GiB, e.g. "64MiB"
- Driftfile:17:1: Missing size: blobs "uploads" states its size, size = "20MiB": it is the enforced limit and what it is billed at, and the platform refuses a size of zero
- Driftfile:20:11: A secret is a reference: secret "STRIPE_KEY": value is write-only and must be written env("NAME"): a literal here would be a credential committed with this fileRead Driftfile:8:15 as "line 8, column 15": the "64MB" that is not a size. Each message says what is wrong and what to write instead. A problem inside a seed file is reported at the seed's own file and line instead, because a JSONL seed is validated line by line: nosql "permit-types" seed: /home/you/my-project/backbone/permit-types.jsonl:4: missing _id.
The platform owns the format, so validation needs a copy of it.
~/.drift/driftfile.schema.json. On a machine that has never run an online command there is nothing to validate against, and the CLI says so rather than passing a file it hasn't checked: "this machine has no copy of the Driftfile format yet, so it cannot be validated." Run drift account login or drift slice list once. It also means a limit the platform adds is accepted as soon as the cached copy refreshes, with no CLI release. drift --version prints the format version the binary implements and the one on this machine. The cached copy is a convenience, not an authority. It lets the CLI refuse a bad file before a round trip, and nothing more: the platform checks every deploy itself, whatever the CLI sent, so a stale, missing or wrong local copy can only cost you a confusing local message, never an invalid slice. The endpoint that serves the format is public and needs no login, on purpose, because a client needs the format before it has credentials. And the copy refreshes on every run rather than being pinned to a version.Plan, then apply
drift plan validates the file, reads the live slice, and prints every difference, the price the platform quotes, and what would be removed or lost. drift apply prints that same plan and asks before the price moves, before anything is removed, and before any data could be lost; it then creates or resizes the slice and deploys what the file declares. Nothing is sent until every question is answered. What runs on the slice is deployed in this order: Backbone, then Atomic and Canvas, then edge. An unchanged Function or Worker is skipped, and --force redeploys every one.
In CI
Plan in one step and apply in another, so the apply runs exactly what was reviewed:
drift file lint
drift plan --out plan.json
drift apply plan.jsondrift file lint fails the job on an invalid file before any account is needed. drift apply plan.json applies exactly the plan that was written, with the answers it recorded, and refuses if the Driftfile, the slice, or what the plan asks changed in between. Without a plan file, answer the questions by flag:
drift apply --approve-price 768 --approve-remove "function GET /bench"The price must be the figure the plan quoted, in cents, and each removal and data loss is agreed to by the address the plan printed for it. A secret reaches the run through the environment (--var NAME=value or the CI's secret store), never through the file.
Ready to ship one?