Migrating from LaunchDarkly
qfg migrate --from launchdarkly imports a LaunchDarkly project into a
Quonfig workspace. The current state of every flag, segment, and environment
is converted losslessly (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).
Quick start (the 3-command flow)
qfg login
qfg workspace create my-team --org my-org
qfg migrate --from launchdarkly \
--source-api-key $LAUNCHDARKLY_API_KEY \
--project my-ld-project \
--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 flag and segment from the LaunchDarkly project, converts them,
validates the result client-side, commits, and pushes.
--project is the LaunchDarkly project key (not its name). It defaults
to default, or to LAUNCHDARKLY_PROJECT_KEY when that is set. If your
flags live in any other project, pass it explicitly, or the migrator imports
the default project instead.
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 LaunchDarkly API token
In the LaunchDarkly UI: Account Settings → Authorization → access tokens. Create an account-level token with read access — that's enough; the migrator never writes back to LaunchDarkly.
Pass it with --source-api-key <token>, or export it:
export LAUNCHDARKLY_API_KEY="api-..."
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 launchdarkly)LAUNCHDARKLY_API_KEY
LAUNCHDARKLY_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.
LaunchDarkly tokens use header auth — no
Bearerprefix. The migrator handles this for you. Rate limits are per-account, shared across all tokens, and unpublished; the migrator backs off onX-Ratelimit-Resetautomatically.
What happens during migration
The migrator imports in one of two modes:
- Config snapshot (default). Roughly ~60 API calls for a typical 500-flag project. Fast — seconds to a couple of minutes. This is the "imports current state" pass and is fully lossless within the documented gap list.
- History backfill (with
--full-summary). Instead of the snapshot, walks the LaunchDarkly audit log and replays each flag change as a git commit with the original author, date, and message, then adds the current segments. Slow — hours for a real account. It keeps a checkpoint, so an interrupted run picks up where it left off.
History retention is plan-gated on the LaunchDarkly side: Developer plans retain only the last 30 days; unlimited history is Enterprise/select-plan only. Anything outside that window is permanently gone in LaunchDarkly and no API can recover it. The migrator probes your account's retention before the slow phase starts and tells you the real horizon up front — you never wait hours expecting two years and silently get thirty days.
--full-summary works only on a first-run import. On a directory that has
already been migrated, the CLI refuses it. To add history later, re-import
from scratch into a fresh directory with --reset --full-summary.
--full-summary also can't be combined with --recent.
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. LaunchDarkly and Quonfig hash percentage rollouts differently. The rollout percentages are preserved exactly, but individual users will land in different buckets after cutover. The report lists every flag with a percentage rollout under a "users will be re-bucketed" heading — plan your comms accordingly.
- Dropped prerequisites. Quonfig has no cross-flag dependency operator in v1. Each dropped prerequisite is named in the report; the downstream flag's own targeting still works, but the gate doesn't.
- Skipped rules. Any clause whose operator couldn't be converted is listed by flag and clause so you can rebuild it by hand.
- Mobile-only flags stop reaching mobile clients. A flag that was
available to mobile SDKs but not to client-side (environment ID) SDKs in
LaunchDarkly (
usingMobileKey: true,usingEnvironmentId: false) is flagged as must-fix: it won't be visible to mobile SDKs after migration. Rebuild client-side access by hand before cutover.
The report also documents informational drops (LaunchDarkly maintainer
metadata, the mobile-key setting on flags that stay client-visible,
customProperties) 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 summarize the must-fix items and propose concrete edits to your remaining LaunchDarkly call sites.
What doesn't migrate cleanly
The full gap list lives in your workspace's .qf/MIGRATION_REPORT.md. The
short version:
- Prerequisites — dropped and reported. The downstream flag's targeting survives; the cross-flag gate does not. Re-implement as in-flag rules or wait for native prerequisite support.
- Individual / context targets — LaunchDarkly's
targetsandcontextTargetsare converted to a leadingPROP_IS_ONE_OFrule on the identifier attribute. Evaluation order is preserved; you lose the dedicated targets-pane UI affordance. privateAttributes— not migrated. It is a LaunchDarkly SDK-side setting, not part of the flag data, so it doesn't appear in the report. Quonfig has no equivalent.- AI Configs — out of scope for v1. The fetcher may enumerate them for the report, but no Quonfig file is emitted.
- Big / synced segments — the segment shell migrates. Membership does not, because LaunchDarkly does not expose unbounded segment members via REST. "Membership unavailable" is recorded in the report.
- Negated comparison / date / semver operators — skipped and reported
per flag and clause. Quonfig has no negated form of
lessThan/greaterThan/before/after/semVerEqualetc., and an algebraic flip would need combinatorial rule expansion (the missing-attribute trap makes it subtle). - Other negated operators — negated
in/contains/startsWith/endsWith/matchesconvert to Quonfig's negated operators with anIS_PRESENTcheck on the same attribute ANDed in front. LaunchDarkly never matches a context that lacks the attribute, and the guard keeps that behavior. NegatedsegmentMatchconverts directly toNOT_IN_SEG. - Regex (
matches) patterns — a pattern outside Quonfig regex v1 is skipped and reported. A multi-pattern clause is joined into one alternation when the result stays inside regex v1; otherwise it is split into one rule per pattern, and a rule that would expand into more than 16 rules is dropped and reported. - Bucketing — as above, individual user-to-bucket assignments change post-cutover even though the rollout percentages are identical.
- Experiment rollouts — converted to plain
weighted_values; thekind: "experiment"framing andseedare dropped and reported. - Mobile-key availability — dropped and reported. Flags that were mobile-only become server-only; see item 4 under Read the migration report.
- Maintainer metadata,
customProperties— dropped and reported. Authorship lives in git history in Quonfig.
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-launchdarkly-1, -2) and migrate into each.
--dry-run summarizes what would happen without writing anything — handy
for sanity-checking a fresh token before committing to a real run.
Command reference
The full flag list is shared with the other sources — see
from-launch → Command reference.
LaunchDarkly-specific notes:
--from launchdarklyselects this source.--source-api-key <token>(env:QUONFIG_MIGRATE_API_KEY, withLAUNCHDARKLY_API_KEYas the fallback) — the LaunchDarkly account-level read token. See Get a LaunchDarkly API token for the full precedence. The older--api-key/LAUNCH_API_KEYpair is a deprecated alias meant for thelaunchsource.--project <ld-project-key>(env:LAUNCHDARKLY_PROJECT_KEY, defaultdefault) — the LaunchDarkly project key to import.--full-summary— opt into the slow Phase-2 audit-log backfill. First-run imports only; can't be combined with--recent.
Run qfg migrate --help for live descriptions.
Next steps
- Troubleshooting common issues
- Migrate your call sites. LaunchDarkly keys normally import unchanged. If
any key had to be renamed (for example, a segment that shared a key with a
flag gets a
-segmentsuffix), 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 LaunchDarkly SDK call sites. - Swap your SDK. Backend: Node, Go, Python, Ruby, Java, .NET. Frontend and mobile: JavaScript (browser), React, React Native, Swift.