Migrating from Flagsmith
qfg migrate --from flagsmith imports a Flagsmith project into a Quonfig
workspace. The current state of every feature, segment, and environment
is converted (modulo a small documented gap list, see below) and either
pushed to a hosted Quonfig workspace or written out as a standalone git
repo your own SDK can read.
This page is the quick-start. The companion artifact you actually need
to read after every run is the .qf/MIGRATION_REPORT.md the migrator
writes inside the workspace directory — see Read the migration report
below.
Use a current qfg (npm install -g @quonfig/cli installs or updates it).
If you migrated with the first Flagsmith release (0.0.51), re-run the
migration: that release imported value-less boolean features as empty
string flags.
Quick start (the 3-command flow)
qfg login
qfg workspace create my-team --org my-org
qfg migrate --from flagsmith \
--source-api-key $FLAGSMITH_API_KEY \
--project 38856 \
--push --workspace my-org/my-team \
--dir ./my-quonfig-workspace
That's it. The migrator clones the hosted workspace into
./my-quonfig-workspace, pulls every feature and segment from the
Flagsmith project, converts them, validates the result client-side,
commits, and pushes.
No cloud account? Drop --push and --workspace, keep --dir.
You'll get a standalone Quonfig workspace git repo on disk that any
backend SDK (Node, Go, Python, Ruby, Java, .NET) can read directly through
its datadir option (WithDataDir in Go). See
Local Workspace (datadir)
for how to point an SDK at it.
Browser-SDK note. The browser SDKs (JavaScript, React, React Native) have no datadir mode. They fetch already-evaluated values over HTTP from the delivery API and poll for updates. To use them with a local-only workspace, serve the directory with
qfg serve; otherwise use the--pushcloud flow. See Frontend SDKs for details.
The two flows side by side — same migration and the same git repo either
way; --push keeps that repo synced to a hosted workspace and adds
hosted delivery:
Get a Flagsmith API token
In the Flagsmith dashboard, create an organisation API key for the Management API (under API Keys in your organisation settings). Don't use an environment key or a server-side SDK key. The migrator only reads from Flagsmith; it never writes back.
Pass it with --source-api-key <token>, or export it:
export FLAGSMITH_API_KEY="..."
The CLI uses the first key it finds, in this order:
--source-api-key, orQUONFIG_MIGRATE_API_KEY(generic, works for any source)--api-key, orLAUNCH_API_KEY(deprecated alias meant for thelaunchsource; the CLI prints a warning when it is used with--from flagsmith)FLAGSMITH_API_KEY
FLAGSMITH_API_KEY is the fallback, so a leftover
QUONFIG_MIGRATE_API_KEY or LAUNCH_API_KEY in your shell takes precedence
over it. Unset those, or pass --source-api-key, if they hold a key for a
different system.
The migrator sends the key as
Authorization: Api-Key <token>for you. When Flagsmith rate-limits a request (HTTP 429), the migrator backs off and retries automatically.
Find your project ID
Flagsmith projects are numeric. Find yours in the URL when you have the project open in the dashboard:
https://app.flagsmith.com/project/38856/environments
^^^^^
Pass it as --project 38856, or set FLAGSMITH_PROJECT_ID=38856. One of
them is required: without either, qfg migrate --from flagsmith stops with an
error. (Before qfg 0.10.0 it fell back to project ID 1, which is almost
certainly not your project.)
What happens during migration
The migrator pulls a full snapshot of the project per run: every feature
with its per-environment featurestate, every segment override and
identity (edge) override, the project-scoped segment pool, the tag pool,
and project metadata (use_edge_identities, etc.).
A typical project of ~500 features takes seconds to a couple of minutes. The fetcher fans out per-environment and per-feature, but it canonicalises weight order and other API quirks before handing data to the converter — see API quirks.
Phase-2 history backfill (replaying the Flagsmith audit log as per-feature git commits) is on the roadmap but not in v1. The migration report captures all the same dispositions either way.
API quirks the migrator handles for you
You don't need to know any of these to use the migrator — they're listed so you can sanity-check that what you see in the report matches your expectations.
- MV-option order — Flagsmith's
/mv-options/returns variations in reverse creation order; the migrator sorts byidascending so variation order in your Quonfig file matches what you see in the Flagsmith dashboard. - MV identity-override weight order — the Flagsmith server reorders
override
multivariate_feature_state_valuesafter write, so idempotency must be presence-based; the converter canonicalises variation order before comparing. - Per-environment identity UUIDs — edge identities have a different
identity_uuidin each environment for the sameidentifier. The fetcher resolves per-environment. - Soft-deletes are invisible — Flagsmith's public REST API hides soft-deleted features (a soft-delete looks identical to a hard-delete from the outside). The migrator literally cannot observe them and the report does not list them.
Read the migration report
This is the most important step. Every run writes a fresh
.qf/MIGRATION_REPORT.md inside the workspace directory (it lives under
.qf/ so it is never pushed as workspace config). It is the honest record
of what came across cleanly and what needs human eyes.
Four things in particular need your attention before you flip an SDK over:
- Users will be re-bucketed. Flagsmith and Quonfig hash percentage rollouts with different salts. The rollout percentages on multivariate features are preserved exactly, but individual users will land in different buckets after cutover. The report lists every multivariate feature under a "users will be re-bucketed" heading — plan your comms accordingly.
enabled=falseon non-boolean features. Flagsmith serves your code's default for a disabled non-bool feature; Quonfig serves the stored value with a note. Each instance is named in the report so you can review whether the stored value is what you actually want.- Skipped operators / rules. Flagsmith's
MODULOand segment-levelPERCENTAGE_SPLIThave no Quonfig equivalent in v1, and aREGEXcondition whose pattern is outside Quonfig regex v1 is skipped too. A segment containing one of these migrates matching no one, rather than with that clause quietly removed (which would widen or narrow it). Each one is listed by segment and reason so you can rebuild it by hand. - Identity-trait references. Every trait name used in a segment condition is listed. Your SDK callers must include those attributes on the evaluation context, or matching rules will silently miss. The report tells you which segments reference which traits so you can audit your call sites.
The report also documents informational drops (paywalled change-requests, scheduled-version drafts, identity-override "individual targets") so nothing is silently lost.
Point your coding agent at it
The fastest workflow:
claude "read .qf/MIGRATION_REPORT.md and tell me what I need to do before \
flipping the SDK to Quonfig"
The report is structured enough that an agent can summarise the must-fix items and propose concrete edits to your remaining Flagsmith call sites.
What doesn't migrate cleanly
The full gap list lives in your workspace's .qf/MIGRATION_REPORT.md,
grouped under its "Conversion notes" section. The short version:
enabled=falseon non-boolean features. Flagsmith would have served your code's default; Quonfig serves the stored value with a note. Bool features servefalse(no surprise).- Identity > segment priority. Identity overrides become a
leading
PROP_IS_ONE_OFrule onuser.key, evaluated before any segment rules. Order matches Flagsmith's behavior; you lose the dedicated identities-pane UI affordance. MODULOoperator. Skipped and reported. No Quonfig equivalent.- Segment-level
PERCENTAGE_SPLIT. Skipped and reported. Quonfig does percentage rollouts at the rule level, not the segment condition level. - Per-environment value-type divergence. A feature whose
envs disagree on type (
stringin Dev,intin Prod, etc.) is coerced tostringand the divergence is named in the report. - Identity traits. Flagsmith identity traits are runtime context the SDK sends — they have no server-side artifact to migrate. The report lists every trait referenced by a segment condition so you can audit your call sites.
NONEsegment rules. A segment rule of typeNONEthat has conditions can't be converted yet. The whole segment is then migrated matching no one and listed in the report, so you can rebuild it.ANYrules (the kind the Flagsmith dashboard saves for each block) convert since qfg 0.10.0: each OR becomes its own Quonfig segment rule, and the blocks stay ANDed, as Flagsmith evaluates them.- Some
:semvercomparisons. SemverNOT_EQUAL,GREATER_THAN_INCLUSIVE, andLESS_THAN_INCLUSIVEhave no Quonfig semver equivalent and are skipped and reported. The other semver comparisons convert to Quonfig's semver operators. - Multivariate identity overrides. Both pinning to a single variation and re-weighting the allocation are preserved.
Plan-gated features the migrator cannot see
- Change requests — Approval-required write flows are a paid-tier feature; on free-tier orgs the API rejects creation. Anything sitting in a change-request workflow is invisible to the migrator and won't appear in the workspace.
- Scheduled changes — Scale-up plan only. Drafts scheduled in the future are invisible to free / start-up tier API tokens.
- Soft-deleted features — Hidden by the public REST API; the
migrator cannot observe
deleted_attombstones (see "API quirks" above).
Re-running
Each qfg migrate run overwrites .qf/MIGRATION_REPORT.md and re-asserts
the workspace state from the source. To experiment with different
conversions or compare runs side-by-side, create distinct workspaces
(e.g. competitor-flagsmith-1, -2) and migrate into each.
--dry-run summarises what would happen without writing anything —
handy for sanity-checking a fresh token and project ID before
committing to a real run.
Command reference
The full flag list is shared with the other sources — see
from-launch → Command reference.
Flagsmith-specific notes:
--from flagsmithselects this source.--source-api-key <token>(env:QUONFIG_MIGRATE_API_KEY, withFLAGSMITH_API_KEYas the fallback) — the Flagsmith Management API token. See Get a Flagsmith API token for the full precedence.--project <id>(env:FLAGSMITH_PROJECT_ID) — the numeric Flagsmith project ID; find it in the project URL. Always set it: without it the migrator uses project ID1.
Run qfg migrate --help for live descriptions.
Next steps
- Troubleshooting common issues
- Migrate your call sites. A Flagsmith feature name that isn't a valid
Quonfig key (letters, numbers,
.,-,_) is renamed. The "Rewritten keys (ACTION REQUIRED)" section of.qf/MIGRATION_REPORT.mdlists each old and new key, and.qf/key-map.jsonhas the same map in machine-readable form (written only when a key was renamed). Point your coding agent at the report to rewrite your Flagsmith SDK call sites. - Swap your SDK. Backend: Node, Go, Python, Ruby, Java, .NET. Frontend and mobile: JavaScript (browser), React, React Native, Swift.