drift Docs
Pages
drift Docs
Start
What is Drift?
The tour, if you are new here.
Use cases
Whether Drift does your thing.
Getting started
Nothing to deployed, in one command.
Architecture
How a slice is put together.
What it costs
The free grant, four unit prices, two rules.
Moving off Azure
Estimate, snapshot and transform a resource group.
Build
Canvas
Static sites, same origin as your API.
Tools
Operate
Auth
Route gates, API keys and your account.
Teams
More than one person on one account.
Security
Boundaries, sandboxing and hardening.
Troubleshooting
Error codes
What went wrong, and what to do about it.
Legal
Acceptable use
What a slice may not be used for.
Data processing
The DPA, and every sub-processor.

drift file

Everything you do with a Driftfile, under one noun, and the three commands that apply it. The file declares one slice: what runs on it and its shape, with each Function's and Worker's memory booking, each database's, collection's and bucket's size, and the slice's limits written beside what they size. drift plan shows what applying it would change and cost, drift apply creates or resizes the slice and deploys, and drift size writes measured bookings back into the file. One noun, so there is nothing to learn about where a verb lives before you can type it.

Five of the drift file commands never leave your laptop: no account, no slice, no network, so “is line 9 a typo?” costs milliseconds instead of a failed deploy.

Command Description
drift file lint [path]Validate a Driftfile exactly as drift plan would, without needing an account, a network or the values of its secrets. It also checks that each handler exists in its backend's source. Exits non-zero on an invalid file, so it can gate a CI job.
drift file explain [path]Describe the Driftfile format: what a block or attribute is, what it takes and what it contains. drift file explain lists the blocks, drift file explain atomic.backend.function and drift file explain atomic.backend.function.memory walk into one, and --recursive prints everything under the path.
drift file resolve [path]Print what one file compiles to: every booking, size and limit, with whatever the file leaves out filled in. --env staging resolves that environment.
drift file fmt [path]Print the file in HCL's canonical layout: two-space indentation and aligned =. Comments, blank lines and the order of everything are kept. --write rewrites the file in place.
drift file new [path]Write a starter Driftfile declaring a slice and one function, with everything the format requires already written. At a terminal it asks for the slice's name (default: DRIFT_SLICE, else the directory name), the first function's method, route and language, and a folder to serve as the site. A flag answers its question in advance (--name, --method, --route, --lang, --canvas <dir>), --yes takes every default, and --force overwrites an existing file. drift apply then creates the slice.

A bare path argument defaults to ./Driftfile, and a directory argument means the Driftfile inside it.

The rest run what the file declares, or measure it:

Command Description
drift file run [environment]Build and run the whole project locally in Docker, with no account and no cloud. --port N picks the host port, --persist keeps Backbone data in a named volume across runs, --no-env-file skips the .env files, and --env is the same as the positional argument.
drift file test [environment]Run it locally, wait for health, run every test block's command against it, and always tear it down. Takes --port, --no-env-file and --env.
drift file stop [environment]Stop the local run. --purge also removes the persisted data volume.
drift file logs [environment]Show logs from the local run. -f/--follow streams new lines instead of printing what's there and exiting.
drift file benchmarkReport what each Function and Worker has cost in memory on the deployed slice, and the size it should book. It only reports; drift size writes.

The four local verbs are one loop: run boots the whole project in Docker, test runs the Driftfile's test commands against it, logs tails it, and stop tears it down.

drift plan

drift plan [environment] compares the Driftfile with the live slice and prints every difference, what it costs and what it removes. It changes nothing: every request it makes is a read, except the platform's price quote, which writes nothing.

Shell
$ drift plan

  slice ada/testnode                                 ~ change

  ~ function POST /rpc          memory 64MiB → 128MiB
  - function GET /bench         deployed code, triggers and history are deleted
    sql chain                unchanged
    worker sequencer          unchanged (digest 9f2c…)

  Price     €5.76 a month → €7.68 a month         (quoted by the platform)
  Restart   yes: the slice restarts once, because its total booked memory changes (192MiB → 256MiB),
            which means a few seconds of errors
  Removes   function GET /bench

  Apply with:  drift apply      (asks for each of the above)
         or:   drift apply --approve-price 768 --approve-remove "function GET /bench"

Each line is a resource and its address, the way the plan names it everywhere: function POST /rpc, function QUEUE orders, field sequencer, sql chain, nosql items, blobs uploads, queue txs, secret STRIPE_KEY, site /, site_auth alice, link billing, allow 203.0.113.0/24, host app.example.com, domain app.example.com, egress, limits.timeout, slots, databases, tier, label team. The mark on the left says what applying does to it:

Mark Meaning
+Added
~Changed
-Removed
blankUnchanged
!Cannot be applied as it stands, for example secret STRIPE_KEY $STRIPE_KEY is not set here: apply would refuse

A slice that does not exist yet is + create, and its price line reads €x.xx a month (quoted by the platform), or free. With nothing to do it prints Nothing to change. That claim is made only for a slice read in full: if some fact the plan compares could not be read, the header reads unchanged (not fully read) instead, and the plan ends on Nothing differs in what could be read. with one line per fact it could not read, naming what it was read for and why, for example site /: sites could not be read (Couldn't list canvas sites: the platform is having trouble. ...). The same cause at several addresses is one line, and a fact that sits at no address of its own names itself. A line carrying a mark still wins: a plan that finds a difference reports it and lists what it could not read beside it. A Data line, could be lost: ..., appears when a store is removed or shrunk, or when limits.backup_retention shortens. Some things the plan reports on purpose:

  • A site the file does not name stays served: the plan prints - site /old still served: no drift command removes a site yet.
  • A domain the file does not name stays attached: apply adds what is declared and reports the rest.
  • A secret is write-only: present ones are set again from their variable on apply, and never compared.
  • An API key is compared by the slice's fingerprint (its last four characters): an unchanged key is not rotated, and a different one reads rotates to the key in $NAME.
  • A booking that shrinks is a removal that apply asks about, and a store that shrinks is a possible data loss.
Flag What it does
--out <file>Also write the plan down, for drift apply <file> to apply exactly it.
--exit-codeExit 0 when the plan is a match, 2 when it would create the slice or found a difference, 3 when a fact could not be read, 1 when the plan fails. Combined with --out, the file is still written. Without the flag a difference exits 0.
--var KEY=valueSet a variable env() reads (repeatable). It yields to the terminal's environment and beats the .env file.
--secret KEY=valueThe same as --var.
--no-env-fileDo not read the .env / .env.<env> file beside the Driftfile.

A fact the plan could not read, such as the slice's sites, secrets, keys, alerts, edge settings, deployed functions or its build, is never taken for a match: with --exit-code, that plan exits 3, with the reason on stderr. A value that is write-only by design, a secret, an API key or a gate password, is never read back, so it is not a fact that could be unread.

drift plan staging plans the environment's own slice. The Driftfile page has the plan reference.

drift apply

drift apply [environment | plan.json] makes the slice exactly what the Driftfile declares, and nothing else. It prints the same plan drift plan prints, then asks before three things, each on its own:

Asked whenAnswered without a terminal by
  • The price
    Asked when
    The monthly figure moves, or a monthly slice is created
    Answered without a terminal by
    --approve-price <cents>, which must be the figure the plan quoted
  • A removal
    Asked when
    Code, a slot, a booking or a limit goes away
    Answered without a terminal by
    --approve-remove "<address>", once per resource
  • A data loss
    Asked when
    A database, collection, bucket or queue holding data is removed or shrunk, or backups are kept for less time
    Answered without a terminal by
    --allow-data-loss "<address>", once per resource

Agreeing to a removal is not agreeing to lose what it holds; each is asked. Without a terminal, an unanswered question stops the apply before anything is sent, and the message lists the flags that answer it. Then, in order:

  1. Checks run first (secrets and passwords set, edge settings valid), before any route is called.
  2. If there is no slice yet, it is created with the file's shape (a free slice from the free preset).
  3. If the shape changed, the slice is resized. The agreed figure goes with the request, so if the price moved between plan and apply the platform refuses and nothing changes: run drift plan again.
  4. What runs on it is deployed: Backbone, then Atomic and Canvas, then edge. An unchanged Function or Worker is skipped.
  5. API keys are set only where the slice holds none or a different one.
  6. A pre_deploy hook runs before anything is sent, and post_deploy once the slice is live.

A file that would move an existing free slice to a priced shape is refused for now; that move is made with drift slice resize.

For CI, write the plan down and apply exactly it:

Shell
drift plan --out plan.json
drift apply plan.json

The plan file carries the answers of the plan it records. It is refused if the Driftfile, the slice or what the plan asks changed in between.

Apply flags

Flag What it does
--approve-price <cents>Agree to the new monthly price, in cents. It must be the figure the plan quoted.
--approve-remove "<address>"Agree to remove a resource, by its address as the plan prints it (repeatable).
--allow-data-loss "<address>"Agree that a resource's data may be lost, by its address (repeatable).
--forceRedeploy every Function and Worker, even if its source is unchanged.
--var KEY=valueSet a variable env() reads (repeatable). It yields to the terminal's environment and beats the .env file.
--secret KEY=valueThe same as --var.
--no-env-fileDo not read the .env / .env.<env> file beside the Driftfile.
Shell
drift apply
drift apply staging
drift apply --approve-price 768 --approve-remove "function GET /bench"

The Driftfile page has the apply reference.

drift size

drift size reads what the slice measured for each Function and Worker, and rewrites the memory line of every one the slice recommends a different size for. Comments and layout stay as they are, and the change is shown as a diff. --dry-run shows it without writing.

The file is changed and nothing else: run drift plan to see what the new bookings cost, and apply them as any other edit. A Function nobody has called yet is left alone, because there is nothing to size it from, and a booking written as memory = var.rpc_memory is not rewritten, because the figure lives somewhere else. drift file benchmark is the read-only half: it prints the same measurements, the calls behind each peak, what is booked and what to book instead.

Environments

When the Driftfile declares environment blocks, drift plan, drift apply, drift file run, drift file test, drift file stop and drift file logs take one by name as a positional argument (the four drift file ones also as --env), and drift file resolve takes it as --env. An environment is another slice from the same file. Its slice is named <slice>-<environment> unless the block names one with slice = "...", and "prod" and "production" are the slice itself. A variable takes the environment's vars value, else its default, so an environment changes only what a variable carries, plus its slice. An environment the file does not declare is refused, naming the ones it does.

Driftfile
slice "shop" {}

variable "rpc_memory" {
  default = "64MiB"
}

environment "staging" {
  vars = { rpc_memory = "32MiB" }
}

atomic {
  backend "default" {
    function "POST /items" {
      handler = "PostItems"
      memory  = var.rpc_memory
    }
  }
}

drift file resolve prints shop with a 64MiB booking, and drift file resolve --env staging prints shop-staging with 32MiB. drift apply staging creates that slice if it does not exist.

Running locally

drift file run builds every function, field and the Canvas site, bakes a thin image on top of the Drift runtime, and launches it detached on localhost: the same code that runs on Drift Cloud, on your own machine. It needs Docker, and only Docker: every language (Go, Rust, Python, Node, PHP, Ruby) builds inside a throwaway container, so no toolchain has to be installed locally. Set DRIFT_RUN_HOST_BUILD=1 to build with your own installed toolchains instead, which is faster and pulls nothing.

Testing before you ship

drift file test is run plus your own e2e commands. It starts the project locally, waits for it to report healthy, exports the instance URL as DRIFT_TEST_URL (the port is chosen at runtime, so read it rather than hardcoding one), and runs the command of every test block. The first non-zero exit fails the run, and the instance is torn down either way.

Driftfile
test "e2e" {
  run = "npx playwright test"
}

Then, with no account and no cloud:

Shell
$ drift file test

A Driftfile with no test block is refused, and the message shows the block to add.

resolve and explain

resolve is the one that pays for itself. It prints what this file compiles to: every Function and Worker with its booking, every store with its size, every limit, every site, and the names of the values it reads from the environment, $NAME and never the value. It prints no price: the platform is the single authority on cost, and drift plan is where that number comes from.

explain answers the other question, the one about the format rather than about your file. drift file explain atomic.backend.function.memory prints what that attribute is, what it takes, and whether it is required. It renders the schema the CLI already caches, which is the same document lint validates against, so the two can never disagree and a key the platform adds is explainable as soon as the cache refreshes.

The platform owns the format, so the CLI needs a copy of it.

The Driftfile schema is fetched on first contact and cached at ~/.drift/driftfile.schema.json. On a machine that has never run an online command, lint and plan refuse rather than printing a tick they can't stand behind, so run drift account login or drift slice list once and it's cached permanently.

When the slice declares more than the Driftfile names

A Driftfile declares the whole slice, so what the live slice holds and the file does not name is a difference like any other. drift plan lists it as a removal: a Function or Worker slot, a booking, a collection, a bucket, a database, a queue, a secret, a link, an allowed network or a host the file leaves out is a - line, and it appears under Removes (and under Data when it holds data). A slot is billed for its booking from the moment it is declared, whether anything runs in it or not, so a slice that books six slots and a file that names five is a plan that removes the sixth.

drift apply asks before it removes each one, and asks again, separately, before losing the data it holds. Nothing is removed on an unanswered question. Without a terminal, --approve-remove "<address>" and --allow-data-loss "<address>" answer for one resource each, with the address exactly as the plan prints it.

Three kinds of resource are never removed by an apply, whatever the file says. A site the file does not name keeps serving, a domain it does not name stays attached, and an alert (alerts are set with drift atomic alert, not in the file) is left in force. The closing report of an apply names what it left, with the command that removes it where one exists.