Flag files

A flag file is a JSON snapshot of one environment's flag definitions. A client in file mode (mode: "file") evaluates in your process from the file, with the same engine and the same results as sync mode, 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/js 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/js 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

Create a client in file mode. It needs no sdkKey and no endpoint.

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

const flags = await ToggldClient.create({
  mode: "file",
  file: "./toggld.flags.json", // the default, so you can leave it out
});

create resolves after the first read of the file. file is valid only with mode: "file". With another mode, create throws a TypeError.

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 switches a client in sync mode or remote mode to file mode with that file, and it takes precedence over 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, when it is set and not empty.
2. The file option, in file mode.
3. ./toggld.flags.json, in file mode.

File formatCopy Anchor Link

The file is the same snapshot that sync 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 30 seconds as a safety net. The sync options do not apply to file mode. 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 mode sends 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.