Config as Code

Declare your service's flags in foredeck.yaml and sync them from CI or your terminal (PRD-16)

Declare your service's flags next to the code that reads them, and sync them from CI or your terminal. Init → edit → sync → evaluate in under 15 minutes:

# 1. init — scaffold foredeck.yaml from your service's current server state
npx foredeck init --service checkout-api \
  --api-url http://localhost:8000 --sdk-key fd_server_acme

# 2. edit — declare a new flag in foredeck.yaml (schema-validated in your editor
#    via spec/foredeck-config.schema.json)

# 3. sync — review the plan, then apply
npx foredeck sync --dry-run     # Terraform-style plan; exits 2 if changes pending (CI gate)
npx foredeck sync               # create/update the declared flags on the server

// 4. evaluate — the client stamps service/env from the file and can evaluate
//    from the file's defaults before the first ruleset fetch
import { createClient } from '@foredeck/sdk-js/node';

const foredeck = createClient({
  sdkKey: process.env.FOREDECK_SDK_KEY!,
  baseUrl: 'http://localhost:8000',
  eventsUrl: 'http://localhost:5000',
  configFile: './foredeck.yaml',   // service/env stamping + defaults bootstrap
});
const { variation } = foredeck.getVariation('new-checkout', userId);

Details

File format — service (required), env, display_name/description/tags, defaults: (flag → default variation), flags[], experiments[], and an envs: per-environment overlay map (flags merge by key, experiments by name). JSON Schema ships at spec/foredeck-config.schema.json.
Ownership & drift — resources created/adopted by sync are managed_by: config; editing them in the UI flips them to drifted. sync never overwrites drifted resources: --accept-remote prints file blocks of the server state (UI change wins until reconciled), --force-local makes the file win. Adoption of UI-created resources requires --adopt or per-resource managed: true — sync never silently seizes UI resources.
Full-state updates — updates always send the complete resolved declared state (the server's PUT resets omitted fields), plus a canonical config_hash used for drift detection.
CI — foredeck sync --dry-run exits 2 when changes are pending; --output json emits a machine-readable plan. foredeck validate checks the file against the schema.
Undeclared-flag validation — with a config loaded, evaluating a flag key that the file doesn't declare warns once per key (onUndeclaredFlag: 'warn' | 'error' | 'ignore'); client.assertDeclared(key) for hard checks.
Browser/edge builds stay node-free: load the file yourself (or bundle it) and pass it as config instead of configFile.

# 1. init — scaffold foredeck.yaml from your service's current server state npx foredeck init --service checkout-api \ --api-url http://localhost:8000 --sdk-key fd_server_acme # 2. edit — declare a new flag in foredeck.yaml (schema-validated in your editor # via spec/foredeck-config.schema.json) # 3. sync — review the plan, then apply npx foredeck sync --dry-run # Terraform-style plan; exits 2 if changes pending (CI gate) npx foredeck sync # create/update the declared flags on the server

// 4. evaluate — the client stamps service/env from the file and can evaluate // from the file's defaults before the first ruleset fetch import { createClient } from '@foredeck/sdk-js/node'; const foredeck = createClient({ sdkKey: process.env.FOREDECK_SDK_KEY!, baseUrl: 'http://localhost:8000', eventsUrl: 'http://localhost:5000', configFile: './foredeck.yaml', // service/env stamping + defaults bootstrap }); const { variation } = foredeck.getVariation('new-checkout', userId);