Flag files

A flag file is a JSON snapshot of one environment's flag definitions. A client that reads a flag file evaluates locally with the same engine and gives the same results, but it makes no network requests. It needs no API, no key, and no network.

Use flag files for:

• Local development without network access.
• Tests and CI that need a known, fixed set of flags.
• Pinning a ruleset that you review and commit.

Download a flag fileCopy Anchor Link

The SDK includes a CLI with one command, pull. It downloads the current definitions for the key's environment and writes them to a file.

npx @toggld/node pull --sdk-key ffk_YOUR_SECRET_KEY

✓ Wrote ./toggld.flags.json — 4 flags, 1 segments (version 3f9c2a1b7d0e…).

The CLI uses the hosted API, https://api.toggld.io, by default. If you host Toggld yourself, pass --api or set TOGGLD_API_URL.

To keep the key out of your shell history, set TOGGLD_SDK_KEY or omit the key. In an interactive terminal, the CLI then asks for the key and hides what you type.

npx @toggld/node pull --out ./fixtures/flags.json --env-name development

OptionsCopy Anchor Link

pull is one-shot. If the file already contains the current version, it writes nothing and reports that the file is up to date. On failure, it prints the reason and exits with status 1.

Use a flag fileCopy Anchor Link

Point a local-mode client at the file. A file-backed client needs no sdkKey and no endpoint.

import { ToggldClient } from "@toggld/node";

const flags = await ToggldClient.create({
  mode: "local",
  sync: { file: "./toggld.flags.json" }, // or `file: true` for ./toggld.flags.json
});

Redirect any client with an environment variableCopy Anchor Link

Set TOGGLD_FLAGS_FILE to make any client read a file, with no code change. It takes precedence over sync.file, and it also switches a remote-mode client to local evaluation from the file.

TOGGLD_FLAGS_FILE=./toggld.flags.json node server.js

The SDK chooses the file in this order:

1. The TOGGLD_FLAGS_FILE environment variable.
2. A string path in sync.file.
3. ./toggld.flags.json when sync.file is true.

File formatCopy Anchor Link

The file is the same snapshot that local mode downloads, wrapped in a small envelope:

{
  "$schema": "https://toggld.dev/schema/local-flags.v1.json",
  "toggld": {
    "environment": "development",
    "apiBase": "https://api.toggld.io",
    "generatedAt": "2026-10-31T12:00:00.000Z",
    "generatedBy": "toggld pull"
  },
  "version": "3f9c2a1b7d0e4d5a",
  "flags": [
    {
      "key": "new-checkout",
      "type": "boolean",
      "enabled": true,
      "variants": { "on": true, "off": false },
      "defaultVariant": "off",
      "offVariant": "off",
      "targeting": [],
      "metadata": {},
      "createdAt": "2026-10-30T09:00:00.000Z",
      "updatedAt": "2026-10-30T09:00:00.000Z"
    }
  ],
  "segments": []
}

version is an opaque string that identifies the snapshot content. The toggld envelope is for people. The SDK ignores it. The flag fields follow the targeting rule format.

Edit a flag fileCopy Anchor Link

The file is plain JSON, so you can review it, diff it, and commit it. You can also edit it by hand, for example to turn a flag on or change a rollout weight.

The SDK watches the file and loads changes without a restart. It also rereads the file every sync.pollIntervalMs as a safety net. The SDK compares the file content, so you do not need to change version when you edit flags by hand.

If the file is missing or not valid, the client logs a warning, keeps its current snapshot, and tries again. Before the first successful read, evaluations return your fallback value with PROVIDER_NOT_READY.

LimitationsCopy Anchor Link

• No updates. A file does not change when someone edits flags in the dashboard. Run pull again to refresh it.
• No telemetry. File-backed clients send no evaluation counts, even when a key is present.
• One environment. A file holds the definitions of the key's environment only.
• Large segment lists. A separate list mode for very large segments is planned. It is not available yet, and it will not work offline. See Segments.