Tooling
Import flags
On this page
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.
OpenFeature flagd
Flag definition files as described by the flagd flag definition reference: flags with state, variants, defaultVariant, targeting (JsonLogic) and shared $evaluators.
{
"$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"] }
}
}| flagd | NanoFlags |
|---|---|
| Variant values | Flag type: boolean, string or number when all variants share that type, otherwise json. |
state: DISABLED | Flag 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. |
$evaluators | Named segments when the evaluator is a plain condition; otherwise inlined where it is used. |
fractional | Two 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. |
targetingKey | The context attribute key. |
user.email | Nested attributes become flat attributes with a dotted name (pass them with that exact name). |
sem_ver, $flagd.timestamp, computed variant names | Not supported: the branch is left out and reported. |
| Keys like headerColor | Normalised 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.
{
"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 } }
]
}
}
}
]
}| Field | Meaning |
|---|---|
flags[].key | Required. Invalid keys are normalised. |
flags[].type | Required: boolean, string, number or json. |
name, description, purpose, permanent, clientExposed | Optional flag details. purpose: release, experiment, operational or permission. |
jsonSchema | Optional, json flags only. Every value is validated against it. |
initialValue | Value 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.
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/falsefor booleans, numbers for number flags, raw text for strings (a quoted JSON string is unwrapped), JSON for json flags. rulesis a JSON array of NanoFlags rules. Rows withoutenvironmentbelong to the source environmentdefault.- 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 concept | NanoFlags | Notes |
|---|---|---|
| Flag with variations | Flag with a type | Mixed value types become a json flag. |
| On/off per environment | enabled | The off value is the source's off variation, or the default when the source has none. |
| Targeting rule | Rule | Conditions are combined with all or any; nested groups become importer-created segments (up to four levels are evaluated). |
| Individual targets | key in [...] | A rule before the other rules. |
| Segment / audience | Segment | Segments are project-wide; a segment that differs between source environments is imported once per version under its own key. |
| Two-way percentage split | Rollout rule | NanoFlags buckets with its own hash, seeded with the flag key: shares are kept, individual contexts may land differently. |
| Split with more than two variations | Rollout of the two largest | Reported 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 attribute | Explicit exists / not exists | Kept exactly where the source's semantics are known. |
Conflicts with existing keys
| Policy | Flags | Segments |
|---|---|---|
skip | The existing flag is left unchanged. | The existing segment is kept; imported rules that reference it use the existing definition. |
rename | Created 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. |
overwrite | Replaces 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.
| Result | Meaning |
|---|---|
| Equivalent | Same value for every generated context. |
| Same shares | Same 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. |
| Differs | At least one context gets a different value; an example is shown. Expected when the conversion reported unsupported features. |
| Not proven | The 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.
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
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=developmentOptions: --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.
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.startedandimport.completed/import.failedwith 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.