Skip to content
NanoFlags
Start free

Tooling

Import flags

Convert flag definitions from a file into a project's drafts: flags, segments and per-environment targeting. An import never publishes; publishing goes through the environment's normal review.

How an import works

  • Source. Upload or paste a file in the dashboard (Flags → Import flags, or Settings → Data), send it with the CLI, or post it to the Management API. For some sources the dashboard can also fetch the definitions with an API token you paste: the token is sent once to NanoFlags' server for that request and is not stored or logged.
  • Dry run. The file is converted and compared with the target project: what will be created, which keys already exist, what cannot be expressed (warnings), which values fail validation, and a fidelity report. Nothing is written.
  • Target. Choose the project and map each source environment to one of its environments (or leave it out). A file without environments (flagd) has one source environment, default.
  • Import. Items are written in chunks of 50 with progress: segments first, then flags. Each item is validated and written on its own, so one invalid value fails only that item. New flags are created; drafts of the mapped environments are edited. Revisions and the published configuration are never touched.
Drafts only
After an import, the environments show unpublished draft changes. Review them (diff, scenarios, “Try a context”), then publish through a change with the environment's approvals and scenario checks, exactly as for hand-made edits.

OpenFeature flagd

Flag definition files as described by the flagd flag definition reference: flags with state, variants, defaultVariant, targeting (JsonLogic) and shared $evaluators.

flags.flagd.json
{
  "$schema": "https://flagd.dev/schema/v0/flags.json",
  "flags": {
    "checkout-split": {
      "state": "ENABLED",
      "variants": { "new": true, "old": false },
      "defaultVariant": "old",
      "targeting": {
        "if": [
          { "$ref": "internalUsers" }, "new",
          { "fractional": [["new", 25], ["old", 75]] }
        ]
      }
    }
  },
  "$evaluators": {
    "internalUsers": { "ends_with": [{ "var": "email" }, "@example.com"] }
  }
}
flagdNanoFlags
Variant valuesFlag type: boolean, string or number when all variants share that type, otherwise json.
state: DISABLEDFlag switched off in the mapped environment; it serves the default variant.
if [c1, v1, c2, v2, …, else]One rule per branch, in order. Nested if inside a branch becomes rules with the combined condition, followed by a rule that serves the default variant (flagd answers null → default there).
== === != !== in < <= > >= starts_with ends_with and or !Conditions. Nested and/or/not groups become importer-created segments (keys ending in -grp-…), because a rule is one list combined with all or any. != and !in also match a missing attribute, as in JsonLogic.
$evaluatorsNamed segments when the evaluator is a plain condition; otherwise inlined where it is used.
fractionalTwo variations: a rollout rule (percentage of the first). One variation: a fixed value. More than two: the two largest shares, rescaled, reported as unsupported. Bucketing attribute: targetingKey → key, or the attribute named in the bucketing expression.
targetingKeyThe context attribute key.
user.emailNested attributes become flat attributes with a dotted name (pass them with that exact name).
sem_ver, $flagd.timestamp, computed variant namesNot supported: the branch is left out and reported.
Keys like headerColorNormalised to header-color (lowercase, digits, - and _). Reported as info: update the key in code.

NanoFlags import format (JSON)

format: "nanoflags.import/v1", segments, and flags with a type and one draft per source environment in NanoFlags rule syntax (the same as a revision bundle). A file written by nanoflags export is accepted too, for copying a project.

flags.json
{
  "format": "nanoflags.import/v1",
  "environments": ["development", "production"],
  "segments": [
    { "key": "staff", "name": "Staff", "match": "any",
      "conditions": [{ "attribute": "email", "op": "ends_with", "value": "@example.com" }] }
  ],
  "flags": [
    {
      "key": "checkout-v3",
      "name": "Checkout v3",
      "type": "boolean",
      "purpose": "release",
      "initialValue": false,
      "environments": {
        "development": { "enabled": true, "default": true, "off": false },
        "production": {
          "enabled": true, "default": false, "off": false,
          "rules": [
            { "id": "staff", "match": "all",
              "conditions": [{ "attribute": "", "op": "segment", "value": "staff" }],
              "serve": { "type": "fixed", "value": true } },
            { "id": "rollout", "match": "all", "conditions": [],
              "serve": { "type": "rollout", "percentage": 10, "value": true, "otherwise": false } }
          ]
        }
      }
    }
  ]
}
FieldMeaning
flags[].keyRequired. Invalid keys are normalised.
flags[].typeRequired: boolean, string, number or json.
name, description, purpose, permanent, clientExposedOptional flag details. purpose: release, experiment, operational or permission.
jsonSchemaOptional, json flags only. Every value is validated against it.
initialValueValue of environments that are not mapped. Default: false / empty string / 0 / null.
environments.<env>enabled (default true), default, off (default: the default value), rules.
segments[]key, name, description, match (all|any), conditions; conditions may reference other segments (op: segment).

NanoFlags import format (CSV)

One row per flag and environment, UTF-8, comma separated, with a header row. Only key and type are required. Columns: key, type, name, description, environment, enabled, default, off, rules, client_exposed, permanent, purpose.

flags.csv
key,type,name,description,environment,enabled,default,off,rules,client_exposed
dark-mode,boolean,Dark mode,"Theme switch",development,true,true,false,,true
dark-mode,boolean,Dark mode,"Theme switch",production,false,false,false,,true
page-size,number,Page size,,production,true,25,10,,
welcome,string,Welcome text,,production,true,Hello,Hello,"[{""id"":""ar"",""match"":""all"",""conditions"":[{""attribute"":""locale"",""op"":""eq"",""value"":""ar""}],""serve"":{""type"":""fixed"",""value"":""أهلاً""}}]",
  • Values: true/false for booleans, numbers for number flags, raw text for strings (a quoted JSON string is unwrapped), JSON for json flags.
  • rules is a JSON array of NanoFlags rules. Rows without environment belong to the source environment default.
  • A row with a value that does not match the type is ignored and reported with its line number.

Other exports

The import dialog lists further supported sources by their export or REST API format. Each adapter maps flags, variations, targeting rules, segments, percentage rollouts and the on/off state per environment to the NanoFlags model, and reports everything it cannot express as a warning. For most of these sources the fidelity check does not re-implement the source's evaluation, so equivalence is reported as not proven: test the drafts before publishing.

Console API exports of feature gates, dynamic configs and segments have their own page, Import gates and dynamic configs; for them the source's evaluation is re-implemented, so the fidelity check and the side-by-side comparison can show real differences. For the whole move, see the Moving to NanoFlags checklist.

Mapping rules

Source conceptNanoFlagsNotes
Flag with variationsFlag with a typeMixed value types become a json flag.
On/off per environmentenabledThe off value is the source's off variation, or the default when the source has none.
Targeting ruleRuleConditions are combined with all or any; nested groups become importer-created segments (up to four levels are evaluated).
Individual targetskey in [...]A rule before the other rules.
Segment / audienceSegmentSegments are project-wide; a segment that differs between source environments is imported once per version under its own key.
Two-way percentage splitRollout ruleNanoFlags buckets with its own hash, seeded with the flag key: shares are kept, individual contexts may land differently.
Split with more than two variationsRollout of the two largestReported as unsupported; the remaining variations are not served.
Prerequisites, regular expressions, dates, semantic versions, per-identity overrides—Reported as unsupported; the rule or item is left out.
Negated condition on a missing attributeExplicit exists / not existsKept exactly where the source's semantics are known.

Conflicts with existing keys

PolicyFlagsSegments
skipThe existing flag is left unchanged.The existing segment is kept; imported rules that reference it use the existing definition.
renameCreated as <key>-imported (or your suffix). Rollouts keep the original key as bucketing seed, so assignments do not move.Created under the new key; references in imported rules are rewritten.
overwriteReplaces the drafts of the mapped environments. A flag's type and details never change; a different type or an archived flag is skipped.Replaces the conditions (part of every environment's draft).

The dialog lets you choose a policy per key; the API takes perKey.

Fidelity check

Before you import, generated contexts are evaluated twice: with the source's semantics and with the NanoFlags engine on exactly the drafts that would be written. Contexts are built from the targeting itself (every literal, its neighbours, missing attributes, combinations) plus sampled identities for splits.

ResultMeaning
EquivalentSame value for every generated context.
Same sharesSame value for every context not decided by a percentage split; the split's shares agree within a statistical tolerance over sampled identities. Individual assignments differ because the hash differs.
DiffersAt least one context gets a different value; an example is shown. Expected when the conversion reported unsupported features.
Not provenThe source's semantics are not re-implemented, the flag uses an existing segment the import keeps, or the conversion approximated something the tested contexts did not reveal.

Side-by-side comparison on your contexts

Generated contexts only cover what the targeting mentions. To check real traffic, send your own sample contexts with a dry run (nanoflags import verify, or contexts in the API, at most 1000): each is evaluated with the source's semantics and with the drafts this file would produce (not the drafts already stored), and every context whose value would differ is listed. Flags that the conflict policy skips are not compared: import verify uses overwrite unless you pass --conflict; in the API, send conflict: "overwrite" to compare flags that already exist. Differences decided by a percentage on both sides are counted separately, because the bucketing hash differs. Sources whose semantics are not re-implemented are reported as not compared.

What the check is, and is not
For flagd the source side is an approximation of the flagd reference evaluator (JsonLogic, fractional, starts_with, ends_with, sem_ver, $ref), following the Go implementation where flagd versions differ. For the NanoFlags format the source side is the NanoFlags engine on the file as written. For gates and dynamic configs it re-implements their documented evaluation, including the source's percentage hashing. Agreement on generated contexts is evidence, not a proof for every possible context.

CLI

sh
export NANOFLAGS_API_TOKEN=nf_api_…        # scope flags:write (+ segments:write if the file has segments)
nanoflags import flags.flagd.json --project shop --env-map default=development --dry-run
nanoflags import flags.flagd.json --project shop --env-map default=development --conflict rename
nanoflags import verify flags.flagd.json --contexts samples.jsonl --project shop --env-map default=development

Options: --format (default auto; .csv files are read as CSV), --env-map source=target,…, --conflict skip|rename|overwrite, --rename-suffix, --label, --dry-run, --json. import verify takes --contexts (JSON Lines or a JSON array) and --flags a,b, writes nothing (its --conflict defaults to overwrite), and exits with 1 when a context differs, when nothing could be compared or when some flag/environment pairs were left out by the evaluation budget. See CLI.

Management API

POST /api/v1/projects/{project}/imports, scope flags:write (and segments:write when the file writes segments). With dryRun: true it answers the preview and the fidelity report (plus comparison when you send contexts); otherwise it imports and answers the import record and the items the database refused. GET /api/v1/projects/{project}/imports/{import} reads an import's progress. With an Idempotency-Key, repeating a completed import answers the first result. Body up to 4 MB. Reference: Management API.

sh
curl -X POST https://edge.nanoflags.io/api/v1/projects/shop/imports \
  -H "Authorization: Bearer $NANOFLAGS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-2026-11-12" \
  -d '{ "format": "flagd", "content": '"$(jq -Rs . < flags.flagd.json)"',
        "envMap": { "default": "development" }, "conflict": "skip", "dryRun": true }'

Limits and audit

  • Up to 5,000 flags and 2,000 segments per import; files up to 10 MB in the dashboard and 4 MB through the API.
  • Editor role in the target project (the organization's two-step verification rule for admins applies). Viewers see the import history.
  • The audit log records import.started and import.completed / import.failed with counts, and every flag, draft and segment written by the import carries the import's id.

After the import

Open the flags, check the drafts and the warnings for each flag, add scenarios for critical targeting, then publish each environment through a change.