CLI
The Quonfig CLI provides powerful tools for creating, modifying, and getting information about your configuration and flags. It also includes TypeScript code generation capabilities to provide type-safe access to your flags and configs.
Installation
On a system with Node 20.9 or newer, run
npm install -g @quonfig/cli
Authentication
Authentication is only required for server-backed commands — qfg pull,
qfg push, qfg create, qfg list, qfg get, qfg set-default, etc. The
local-only commands — qfg init, qfg verify, qfg generate,
qfg config-schema, and qfg migrate — work without an account. If you
just want to use Quonfig as a local git-backed config store, you can skip
this section entirely. See the
Open Source / Fully Local how-to for that
path.
To use the hosted features, authenticate with Quonfig:
qfg login
This prints a sign-in URL and code; press Enter to open it in your browser. One login covers every organization you belong to, so you don't need a separate login per workspace. To aim a command at a particular workspace, pass --workspace <org>/<workspace> (-w), or change your saved default with qfg workspace switch.
For additional details about authentication and troubleshooting, see the login command documentation below.
Usage
See qfg --help for all the available commands. qfg [COMMAND] --help will give you detailed information about a given command.
qfg is designed for humans first, but all commands support a --json flag to output JSON instead.
For build steps, migrations, and one-shot scripts that read configuration from process.env before user code runs (e.g. drizzle-kit migrate, next build), use qfg run to resolve Quonfig configs into env vars and exec a child process.
Global Flags
These flags are available for all commands:
--verbose- Enable verbose output for debugging and detailed logging--no-color- Disable colored output (useful for CI/CD or when piping output)--interactive / --no-interactive- Turn prompts on or off (on by default; prompts are skipped anyway when there is no terminal)--json- Format output as JSON instead of human-readable text--workspace <org>/<workspace>(-w) - The workspace to act on (commands that talk to a hosted workspace). OverridesQUONFIG_WORKSPACEand your saved default.
Examples:
# Get detailed logging information
qfg list --verbose
# Generate clean output for scripts
qfg get my.config --no-color --json
# Force non-interactive mode for automation
qfg create my.flag --type boolean-flag --value=true --no-interactive
# Act on a specific workspace
qfg list --workspace acme/web
TypeScript Code Generation
⭐ Recommended: The generate command creates TypeScript definitions and type-safe clients for your Quonfig configuration, providing autocomplete and type safety in your IDE.
generate can read from either a local copy of your workspace (paired with qfg pull) or directly from the API in one shot — see the generate reference for the in-memory mode.
Quick Start
# Step 1: clone or update your workspace config files locally
qfg pull --dir ./my-config
# Step 2: generate TypeScript definitions from the local files
qfg generate --dir ./my-config
To avoid repeating --dir in every command, set the QUONFIG_DIR environment variable:
export QUONFIG_DIR=./my-config
qfg pull
qfg generate
This generates TypeScript files in the generated/ directory:
quonfig-client-types.d.ts- Type definitions for React/JavaScriptquonfig-client.ts- Type-safe React/JavaScript client
Filter: The react-ts target only includes configs with "Send to frontend SDKs" enabled or configs of type FEATURE_FLAG. If a config is missing from generated types, check that setting in the Quonfig dashboard.
Generate for Node.js
qfg pull --dir ./my-config
qfg generate --dir ./my-config --targets node-ts
This generates:
quonfig-server-types.d.ts- Type definitions for Node.jsquonfig-server.ts- Type-safe Node.js client
The node-ts target includes all configs regardless of client SDK settings.
Generate for Both Platforms
qfg pull --dir ./my-config
qfg generate --dir ./my-config --targets react-ts,node-ts
CI/CD Integration
Run both steps in your pipeline to keep generated types in sync with your workspace:
qfg pull --dir ./my-config
qfg generate --dir ./my-config --output-directory ./src/generated
In CI there is no browser to qfg login with, so authenticate with an API
key instead: set QUONFIG_API_KEY and name the workspace with
QUONFIG_WORKSPACE=<org>/<workspace> or --workspace. If the key is a
service-account key (qf_sa_...), name the workspace by its UUID
rather than org/workspace — a service account has no user-level workspace
list to resolve a slug against. See
Environment Variables.
Configuration File
Create a quonfig.config.json file in your project root to customize output:
{
"outputDirectory": "src/generated",
"targets": {
"react-ts": {
"outputDirectory": "src/client/generated",
"declarationFileName": "quonfig-types.d.ts",
"clientFileName": "quonfig-client.ts"
},
"node-ts": {
"outputDirectory": "src/server/generated",
"declarationFileName": "quonfig-server-types.d.ts",
"clientFileName": "quonfig-server.ts"
}
}
}
Using Generated Types
Once generated, import and use the type-safe clients:
// For React — the generator emits both a QuonfigTypesafeReact class
// and a ready-to-use hook bound to it.
import { useQuonfig, QuonfigTypesafeReact } from './generated/quonfig-client';
function Nav() {
const q = useQuonfig();
return q.buildDarkMode() ? <DarkNav /> : <LightNav />;
}
// For Node.js — wrap a Quonfig instance to get typed accessors.
import { Quonfig } from '@quonfig/node';
import { QuonfigTypesafeNode } from './generated/quonfig-server';
const quonfig = new Quonfig({ sdkKey: process.env.QUONFIG_BACKEND_SDK_KEY! });
await quonfig.init();
const typed = new QuonfigTypesafeNode(quonfig);
typed.buildDarkMode(); // boolean, no string keys
typed.get('build.dark-mode'); // same value, key autocompleted
Commands
init
qfg init [directory] scaffolds a new Quonfig workspace in the given
directory (the current directory by default), or refreshes an existing one.
Fully offline — no login required.
It creates:
- A git repo (or reuses an existing one) with a pre-commit
qfg verifyhook - The workspace directory layout:
configs/,feature-flags/,segments/,log-levels/,schemas/ - A
quonfig.jsondescribing the workspace and its environments - A managed
README.md,CLAUDE.md, andAGENTS.mdthat explain the local-only workflow to humans and AI agents - Sample configs so you have working files to copy from (on a first init,
unless you pass
--no-samples)
Options:
--samples/--no-samples— include sample configs. Defaults to yes on a first init and no when refreshing an existing workspace.--workspace <org>/<workspace>(-w) — pin the workspace identity inquonfig.json(only matters if you later runqfg pushagainst a hosted account)--dry-run— show what would be written without writing anything
Examples:
# Scaffold a brand-new workspace (samples included)
qfg init ./my-config
# Scaffold without samples, in the current directory
qfg init --no-samples
# Preview what a refresh would change
qfg init --dry-run
# Refresh templates in an existing workspace (idempotent — safe to re-run)
qfg init
A workspace made by qfg init without --workspace is local-only. Commands
that write to a hosted workspace (create, delete, set-default,
set-rollout, log-level, override and activity restore) refuse to run
inside it, because they would change a hosted workspace rather than these
files. Edit the JSON files and run qfg verify instead. To write to a hosted
workspace from there anyway, pass --workspace <org>/<workspace> or set
QUONFIG_WORKSPACE.
After qfg init, the next things you'll run are
qfg verify (validation) and qfg generate
(typed SDK client). You can then point any Quonfig SDK at this directory
with datadir and you're done — see
Open Source / Fully Local.
verify
qfg verify validates every JSON file in a Quonfig workspace against the
canonical schema and against cross-file rules. Fully offline.
It checks:
- JSON syntax and schema conformance (field names, value types, operator enums)
- Filename matches the
keyfield - No duplicate keys across the workspace
- Segment references (
IN_SEG/NOT_IN_SEG) resolve to real segments - Schema references (
schemaKey) resolve to real schemas - Every schema compiles, and every value of a schema-bound config matches its schema
- Variant-only configs only emit declared variants
Examples:
# Verify the current directory
qfg verify
# Verify a specific workspace path
qfg verify ./my-config
A pre-commit git hook is installed by qfg init to run this automatically.
generate-new-hex-key
qfg generate-new-hex-key generates a cryptographically secure hex key suitable for encrypting config values with the --secret flag.
Example:
qfg generate-new-hex-key
This outputs a 64-character hex key like:
a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456
Use this key when creating or updating configs with encryption:
# Create an encrypted config using the generated key (prompts for the value, masked)
qfg create my.secret --secret --secret-key-name "my-encryption-key"
See Secret Management for the full setup.
Use cases:
- Encrypting sensitive configuration values
- Setting up encryption keys for different environments
- Generating keys for config value protection
pull
qfg pull clones or updates a local copy of your workspace config files. generate reads from this copy when one exists, and it is also how you edit flag JSON directly for anything beyond the set-default / set-rollout shortcuts.
Options:
--dir <path>- Local directory to clone/update (defaults toQUONFIG_DIR, then the nearest directory at or above the current one that has aquonfig.json)--workspace <id>(-w) - Workspace to pull (defaults to your saved default workspace)--rebase- When your local commits and the workspace'smainhave diverged, replay your commits on top ofmain. Without it,qfg pullstops and tells you to re-run with--rebase.
Examples:
# Clone or update into a local directory
qfg pull --dir ./my-config
# Use QUONFIG_DIR env var instead of --dir
export QUONFIG_DIR=./my-config
qfg pull
Editing JSON for targeting rules
Once you have a local copy, editing the JSON file is how you express rules that go beyond a catch-all default or a simple percentage rollout — for example "this one user gets true, everyone else false", segment membership, or custom properties. See the Targeting rules section below for the full workflow and a sample rule.
After editing files:
qfg verify ./my-config # validate JSON before pushing
git -C ./my-config add -A
git -C ./my-config commit -m "feat: target beta cohort"
git -C ./my-config push
push
qfg push sends local config changes up to your hosted workspace. It
validates the workspace first (the same checks as qfg verify),
then shows a summary of what will change and asks you to confirm.
Before it pushes, it checks that the directory belongs to the workspace you're
pushing to: a workspace pin in quonfig.json, or a git origin that points
at a different workspace, makes it refuse. Destructive pushes (10 or more
deletes, at least a quarter of the files, or a directory with no workspace pin)
make you type the workspace slug to confirm.
Options:
--dir <path>- Local directory to push (defaults toQUONFIG_DIR, then the nearest directory at or above the current one that has aquonfig.json)--workspace <org>/<workspace>(-w) - Workspace to push to (slug or UUID; defaults to your saved default workspace)--yes- Skip the normal yes/no confirmation. It never skips the typed-slug confirmation.--skip-validate- Skip the validation step--message <msg>(-m) - Commit message when the directory is not a git repo. In a git checkout,qfg pushpushes what you have already committed and ignores this flag.--no-pin-write- Don't offer to write the workspace pin intoquonfig.jsonafter a successful push
Examples:
qfg push --dir ./my-config
qfg push --dir ./my-config --workspace acme/web
Proposing instead of going live
qfg push --propose pushes the branch you have checked out as a change
request. Nothing goes live until someone with rights merges it (see
qfg cr). It needs a clone of the workspace and a branch other than
main. It does not ask for confirmation, so --yes is not needed. Walkthrough:
Propose a change for review.
Options:
--propose- Push this branch as a change request instead of going live--title <title>- Change request title (with--propose). Without it, the title is the commit message for a one-commit branch, or the branch name.--description <text>- Change request description (with--propose)
git -C ./my-config switch -c turn-on-checkout
git -C ./my-config commit -am "Turn on checkout for beta"
qfg push --dir ./my-config --propose --title "Turn on checkout for beta"
# Proposed change request #7 from branch turn-on-checkout.
# https://app.quonfig.com/workspaces/<workspace-id>/change-requests/7
# NOT LIVE
# It goes live only when someone with rights merges it. Check on it: qfg cr show 7
A later plain qfg push on the same branch updates the change request and
prints Updated change request #7 with this push. With --json, a propose
push returns
{"proposed": true, "applied": false, "branch", "commitSha", "changeRequest": {"number", "url", "status"}}.
cr
qfg cr lists, shows, merges and closes change requests. Every cr command
takes --json and -w <org>/<workspace> (defaults to the workspace pin in
quonfig.json, then your saved default workspace).
| Command | What it does |
|---|---|
qfg cr list | List open change requests |
qfg cr show <ref> | Show the diff a merge would land, then status, proposer, conflicts, and whether you can merge or close |
qfg cr merge <number> | Merge into main. It goes live. |
qfg cr close <number> | Close without merging. Nothing goes live. |
cr list
Options:
--mine- Only change requests you proposed--status open|merged|closed|all- Which change requests to list (default:open)--limit <n>- Most rows to return (1-200; the server default is 50)
qfg cr list
# #7 open turn-on-checkout Ana Lee 2026-11-13 Turn on checkout for beta
qfg cr list --status merged --limit 10 --json
cr show
<ref> is the number (7 or #7) or the branch name. Use
refs/heads/<name> for a branch whose name is a number. The diff comes first.
The title and description are the proposer's own words and are not checked by
Quonfig.
qfg cr show 7
qfg cr show turn-on-checkout
cr merge
Shows the change request and its diff, asks
Merge change request #7 into main? It goes live. [y/N], then merges only if
the branch still points at the commit you were shown. The server checks your
permissions on every changed file against main as it is now.
Options:
--yes- Skip the confirmation. Without a terminal,qfg cr mergerefuses to run unless you pass it.
qfg cr merge 7
# Merged change request #7 into main as 20f4c67. It is live.
Agents: never merge a change request you did not author without a person telling you to.
cr close
The proposer can always close their own change request; anyone else needs the permissions that merging it would need. The branch is deleted on the server if it still points at the proposed commit.
Options:
--note <text>- Why it was closed (shown on the change request)
qfg cr close 7 --note "superseded by #8"
# Closed change request #7.
# Its branch was deleted on the server.
serve
qfg serve reads a local datadir and exposes it over the HTTP wire
protocol the browser and React Native SDKs already speak. Use it when
you want browser-side feature flags powered by a checked-in datadir —
server-side SDKs read a datadir directly, so they don't need this.
qfg serve --datadir ./our-config --environment development
# → http://127.0.0.1:6580
Options:
--datadir <path>- Path to the workspace. Without the flag,qfg serveusesQUONFIG_DIR, then./our-config, then./.quonfig(relative to the current directory; it does not search parent directories the waypullandpushdo)--environment <slug>- Environment to evaluate. The flag wins; otherwiseQUONFIG_ENVIRONMENT; otherwisedevelopment.qfg servehosts a service, so it reads the variable the same way an SDK does (see Environment Variables).--port <n>- TCP port (default6580)--host <addr>- Bind address (default127.0.0.1; non-loopback requires--allow-non-loopback)--frontend-sdk-key <key>- If set, requireAuthorization: Basic 1:<key>on every request--cors-origin <url>- Allowed CORS origin (repeatable; default*)--watch/--no-watch- Reload the envelope when the datadir changes (default on)
See Serve a Datadir to Browser SDKs for the full how-to, including SDK init snippets and production positioning.
generate
qfg generate creates TypeScript definitions and type-safe clients for your Quonfig configuration.
It can read from either:
- A local directory. Explicitly via
--dir/QUONFIG_DIR, or auto-detected: if neither flag is set and the current directory (or an ancestor) contains aquonfig.json,generateuses that. No login required — this is the path the Open Source / Fully Local workflow uses. - The API. When no local workspace can be found and
--workspaceis given (or active credentials are set),generatemints a read token, clones the workspace into a temp dir, generates from it, and cleans up. Use this in CI or one-shot scripts where you don't want to keep a working copy on disk.
Options:
--dir <path>- Path to local config directory (defaults toQUONFIG_DIRenv var). When unset,generatewalks up from cwd looking forquonfig.json; if it finds one, it uses that. Otherwise it falls back to fetching from the API.--workspace <slug-or-id>- Workspace to fetch when running without a local workspace. Required ifQUONFIG_API_KEYis set withoutQUONFIG_WORKSPACE. Passing--workspaceskips the cwd auto-detect and goes straight to the API path.--targets <targets>- Specify target platforms:react-ts(default) ornode-ts--output-directory <dir>- Custom output directory
Examples:
# Pull-then-generate (keeps a local copy)
qfg pull --dir ./my-config
qfg generate --dir ./my-config
# One-shot generate from the API (CI / no local copy)
qfg generate --workspace acme-prod --targets node-ts
# Generate for Node.js from a local dir
qfg generate --dir ./my-config --targets node-ts
# Generate for both platforms
qfg generate --dir ./my-config --targets react-ts,node-ts
# Custom output directory
qfg generate --dir ./my-config --output-directory src/generated
This generates:
- Type definitions (
.d.tsfiles) with full TypeScript support - Type-safe client classes with camelCase method names
- IntelliSense autocomplete for all configs and feature flags
- Context-aware typing for better developer experience
For detailed setup instructions, configuration options, and usage examples, see the TypeScript Code Generation section above.
login
qfg login authenticates you with Quonfig using a device sign-in flow: it prints a URL and a code, and pressing Enter opens the URL in your browser. Once you approve, it stores a token for each organization you belong to, so later commands can reach any of your workspaces.
Options:
--json- Format output as JSON
Example:
qfg login
On success it prints your default workspace. To pick a different default, run qfg workspace switch; to target another workspace for a single command, pass --workspace <org>/<workspace>.
Older CLI versions used --profile to manage multiple accounts. You no longer need it: one login covers all your organizations. --profile still works but is hidden from help, and qfg profile now runs qfg workspace switch.
logout
qfg logout clears all stored authentication tokens from your local machine. After logging out, you'll need to run qfg login again to authenticate.
Example:
qfg logout
This clears the tokens for every organization and is useful for security, troubleshooting authentication issues, or switching accounts.
whoami
qfg whoami shows the email you're logged in as and the organizations you belong to, with your role in each and a marker on the active one.
qfg whoami
list
qfg list shows keys for your configurations, feature flags, log levels, schemas, and segments. By default, all types are shown, but you can filter to specific types.
Options:
--configs- Include only configs--feature-flags- Include only feature flags--log-levels- Include only log levels--schemas- Include only schemas--segments- Include only segments--json- Format output as JSON
Examples:
qfg list
qfg list --feature-flags
qfg list --configs --feature-flags
qfg list --json
When you specify one or more type flags, only those types are included in the output.
info
qfg info NAME shows detailed information about a specific config, feature flag, or other resource, including current values across environments and recent evaluation statistics.
Example:
qfg info my.config.name
This displays:
- Current values per environment
- Links to the web console
- Usage statistics over the last 24 hours
- Evaluation breakdowns by value
contexts search
qfg contexts search <contextType> <query> finds a context's key from a name, so a targeting rule can match the key (organization.key, user.key) instead of a slug or email.
Options:
--environment <env>- Only contexts reported from this environment (default: all)--limit <n>- Maximum matches, 1-100 (default 20)--json- Print{"contexts": [{"key", "name", "email"?}]}
Example:
qfg contexts search organization acme
# KEY NAME EMAIL
# org_8f3k2 Acme Corp ops@acme.example
#
# Target these in a rule with propertyName "organization.key".
NAME and EMAIL are blank when the context never reported them. Pass a key as the query to see its name. The search covers only contexts your SDKs have reported, so no match means the key is unknown — get it from whoever owns that customer rather than targeting a slug or email. Full semantics: Finding a context's key.
cleanup list
qfg cleanup list shows the feature flags marked ready for cleanup, with how often each was evaluated recently. Pass --all to prospect instead: it shows every flag and config in the workspace, marked or not, so you can see what has gone quiet.
Options:
--all- Every flag and config, not only flags marked ready for cleanup--environment <env>- Count evaluations in this environment only (default: all environments)--json- Structured rows, including a per-environment breakdown
Examples:
qfg cleanup list
qfg cleanup list --all
qfg cleanup list --all --environment production --json
Columns:
EVALS_24H,EVALS_2D,EVALS_7D,EVALS_30D- evaluation counts over UTC calendar daysLAST_EVAL- the most recent day with any evaluationsCLASS-quiet(no evaluations in the last 2 days) oractiveKINDandMARKED- shown with--allonly
Quiet rows sort first, oldest at the top. A - in LAST_EVAL means no evaluations in the last 90 days, not "never". Evaluation counts are only kept for 90 days.
Quiet is not proof of unused. These can all look quiet while still in use:
- a config read once at process start;
- an SDK with evaluation telemetry turned off;
- a code path that runs once a year.
Check the code before you delete anything.
Finding a candidate and retiring it are separate steps:
- A flag: mark it ready for cleanup in the Quonfig app. Then run
qfg cleanup remove <key>to hand the code removal to your coding agent. - A config: there is no marker. Once the code no longer reads it, delete it.
AI agents can get the same data from the MCP tool get_eval_activity (see Finding cleanup candidates).
interactive
qfg interactive (or just qfg) launches an interactive CLI mode where you can browse and manage your resources through a menu-driven interface.
Example:
qfg
qfg interactive
This provides an easier way to explore your configs and flags without remembering specific command syntax.
override
qfg override writes a top-priority rule on a flag, keyed on the dev-only quonfig-user.email property, that fires only for SDK clients which set your email in their context. This lets you test a value locally without affecting anyone else. You must qfg login first — the user identity comes from your saved tokens.
Surface:
qfg override— list flags where you have an override (in the current env).qfg override <key> <value>— set an override. The value's type is inferred:true/false→ bool, integer → int, decimal → double, JSON-shaped ({...}/[...]) → json, anything else → string.qfg override <key> --remove— remove your override on<key>.qfg override --clear— remove all of your overrides in the current env.
Flags:
--env <env>— environment to operate in. Required.qfg overridenever readsQUONFIG_ENVIRONMENT, so a variable left over from local development cannot pick the environment a write lands in.--remove— remove your override on the given key.--clear— remove every override you have in this env.
Examples:
qfg override # list your overrides
qfg override my.flag true # bool
qfg override my.flag 42 # int
qfg override my.flag '{"a":1}' # json
qfg override my.flag --remove # remove just this one
qfg override --clear # remove all of yours
qfg override my.flag true --env=staging # operate in a specific env
Overrides on production are accepted but inert for SDK clients that don't set quonfig-user.email in their context (most production SDKs don't), so the CLI prints a soft warning when you target production.
For the full picture — how the override rule is stored, how SDKs inject your identity from qfg login, the per-SDK setup, and how to use overrides from frontends — see Personal Overrides.
Targeting rules
Quonfig evaluates a flag by walking its rules in order, and the last rule is normally the fallback: an unconditional rule that decides what users receive when no targeting rule matches. The CLI gives you these ways to change what those rules return:
| You want to… | Use |
|---|---|
| Set the fallback (what users get when no targeting rule matches) | qfg set-default |
| Run a percentage rollout / A-B test / canary | qfg set-rollout |
| Set one value for EVERYONE, deleting that environment's targeting rules | qfg set-default --replace-targeting |
| Target specific customers or users, a plan, a segment, or any custom property | Edit the JSON config directly |
set-default and set-rollout change only the fallback: every targeting rule in that environment is kept unless you pass --replace-targeting.
To target a particular customer or user, match their key (organization.key, user.key), not a slug or email — run qfg contexts search to find it from a name.
override is deliberately NOT on this list — it only affects SDK clients that send your quonfig-user.email in their context. For production targeting, reach for one of the options above.
Editing JSON directly
The local JSON config supports every targeting operator the dashboard UI supports (PROP_IS_ONE_OF, IN_SEG, PROP_MATCHES, etc.). Two commands print the operator reference:
qfg config-schema # human-readable operator reference + worked example
qfg config-schema --json-schema # machine-readable JSON Schema (e.g. for IDE completion)
Every config file starts with a $schema field pointing at https://api.quonfig.com/schemas/v1/stored-config.json, so editors that understand JSON Schema give you autocomplete and validation with no setup.
Sample rule — target a single user
To turn forcerank.my.flag on for one user and off for everyone else, first look up their key:
qfg contexts search user alice@acme.dev
# KEY NAME EMAIL
# u_41d9a2 Alice Smith alice@acme.dev
Then express "user.key == u_41d9a2 → true, everyone else → false":
{
"key": "forcerank.my.flag",
"type": "feature_flag",
"valueType": "bool",
"default": {
"rules": [
{
"criteria": [
{
"operator": "PROP_IS_ONE_OF",
"propertyName": "user.key",
"valueToMatch": { "type": "string_list", "value": ["u_41d9a2"] }
}
],
"value": { "type": "bool", "value": true }
},
{
"criteria": [{ "operator": "ALWAYS_TRUE" }],
"value": { "type": "bool", "value": false }
}
]
},
"environments": [],
"variants": []
}
End-to-end workflow:
qfg pull --dir ./my-config # clone or refresh local copy
$EDITOR ./my-config/feature-flags/forcerank.my.flag.json
qfg verify ./my-config # catch typos: unknown operators, missing propertyName, etc.
git -C ./my-config add -A
git -C ./my-config commit -m "feat: target u_41d9a2 for forcerank.my.flag"
git -C ./my-config push
qfg verify validates against the same schema the SDK uses, so a passing verify is a strong signal the rule will evaluate correctly.
schema
qfg schema NAME gets or sets a schema document in your workspace. A schema is a plain JSON Schema document; a JSON config that names it in schemaKey must match it, and qfg generate uses it to type that config.
Options:
--get- Print the schema document--set-json-schema <schema>- Create or replace the schema. Pass the JSON inline, or@path/to/file.jsonto read it from a file.--protected/--no-protected- Store the schema as protected, or move it back to standard storage. On an update, leave both off to keep the schema where it is. A new schema is standard unless you pass--protected.--set-zod <schema>- Deprecated alias for--set-json-schema. It takes JSON Schema, not a Zod expression.
Examples:
qfg schema my-schema --get
qfg schema my-schema --set-json-schema='{"type":"object","properties":{"url":{"type":"string"}},"required":["url"]}'
qfg schema my-schema --set-json-schema=@schemas/my-schema.json --protected
workspace
qfg workspace shows your active workspace, the organizations you have tokens for, and every workspace you can reach.
qfg workspace
workspace switch
qfg workspace switch [<org>/<workspace>] changes your saved default workspace, the one commands use when you don't pass --workspace or set QUONFIG_WORKSPACE. Without an argument it opens an interactive picker.
qfg workspace switch
qfg workspace switch acme/production
workspace create
qfg workspace create <slug> provisions a new workspace under one of your organizations. Useful for agent-driven setups and scripted environments where you don't want to click through the UI.
Options:
--name <name>- Display name (defaults to the slug)--org <slug-or-id>- Organization slug or UUID. Required if your account has more than one org.
Examples:
qfg workspace create my-new-workspace
qfg workspace create acme-prod --name "Acme Production" --org acme-corp
On success, prints the workspace ID, slug, Gitea repo URL, and the default environments (development, production, staging). Returns a non-zero exit code with a clear message on slug collisions, missing org membership, or auth failure.
workspace bootstrap
qfg workspace bootstrap --dir <path> lands a local git repo, with its
commit history, on a freshly created workspace. This is the move from the
fully local workflow to a hosted account
for anyone who wants to keep the history they built up locally; qfg push
lands the same files as a single commit.
Which workspace it pushes to is resolved the same way push, pull and
sync resolve theirs, in this order:
QUONFIG_WORKSPACE, if set (<org>/<workspace>, or the workspace UUID).- The
workspacepin in<dir>/quonfig.json, if the directory has one. - Your saved default workspace (shown by
qfg workspace, changed withqfg workspace switch).
The confirmation prompt names the workspace that won, so check it before answering. If the directory is pinned to one workspace and something else selects another, bootstrap refuses and pushes nothing.
Bootstrap is for a fresh workspace only: one that holds no configs,
flags, segments, log levels or schemas yet. A workspace that is already in
use is refused with a pointer to qfg push --dir <path>. It never
force-pushes: your history is replayed onto the workspace's own first
commits, and your local branch is not moved. On success it prints the
commands that point your clone at the workspace.
Options:
--dir <path>- The local git repo to push (defaults to the current directory)--skip-validate- Skip config validation before pushing
Examples:
qfg workspace bootstrap --dir ./my-config
QUONFIG_WORKSPACE=acme/prod qfg workspace bootstrap --dir ./my-config
Bootstrap needs no git identity on the machine: on a CI runner or a fresh
laptop with no user.name / user.email, the replayed commits keep your
authors and are committed as quonfig migrator.
set-default
qfg set-default NAME sets the fallback value for a flag or config in one environment — the unconditional rule at the end of that environment's rule list, i.e. what users receive when no targeting rule matches.
Targeting rules and percentage rollouts above the fallback are kept, and the command reports how many (an environment with no targeting rules gets no such sentence):
qfg set-default my.flag.name --value=true --environment=staging
# ✔ Set staging fallback to `true`. Kept 2 targeting rule(s); matched users still
# receive their targeted value. To set for everyone, add --replace-targeting.
If the environment has no rules of its own yet it inherits the flag's default rules. Those rules are copied into the environment first, then the fallback is set — so the targeting it was inheriting keeps working, the same shape the UI writes when an environment stops inheriting.
To turn a flag on or off for everyone, including users matched by targeting rules, add --replace-targeting. That collapses the environment to a single unconditional rule and deletes its targeting rules:
qfg set-default my.flag.name --value=false --environment=production --replace-targeting
# ✔ Set production to `false` for everyone. Replaced 2 targeting rule(s); previous version 9f2c1ab.
To set or rotate a secret, add --secret and pass the value with --value-from-env <VAR> or --value-stdin so it stays out of your shell history: qfg set-default my.api.key --environment=production --secret --value-from-env STRIPE_LIVE_KEY --confirm. Use --environment="[Default]" to write the default rules every environment without its own inherits. The output shows a redacted fingerprint, never the value, and --json returns {redacted: true, fingerprint, length, last4?} in place of value. Secrets are string-only, so --secret on a json or other non-string config is refused. See Secret Management.
The deleted rules stay in git history — previous version names the commit to restore from. Under --json the same numbers come back as previousCommitSha + replacedTargetingRuleCount; a normal (surgical) write returns keptTargetingRuleCount. Both counts are omitted when they are 0, so a script should treat a missing field as "no targeting rules were involved", not as an error.
set-rollout
qfg set-rollout NAME makes a percentage rollout (gradual rollout / A-B test / canary) the environment's fallback:
qfg set-rollout my.flag --environment production --true-percent 20
qfg set-rollout my.flag --environment production --weights "red:33,green:33,blue:34"
It follows the same rules as set-default: targeting rules above the fallback are kept and reported, an environment with no rules of its own is copied from default first, and --replace-targeting rolls everyone into the split by deleting that environment's targeting rules.
create
qfg create NAME creates a new flag or config in Quonfig. You can use this to create basic values, encrypted secrets, or values provided by ENV vars.
Supported types: boolean-flag, boolean, string, double, int, string-list, json, duration, log_level
A duration value is an ISO 8601 duration such as PT30S, PT5M, PT1H30M or P1DT6H: optional days, then T and hours, minutes and seconds; only seconds may have a fraction (PT1.5S).
Examples:
# Basic types
qfg create my.new.string --type string --value="hello world"
qfg create my.feature --type boolean-flag --value=true
qfg create my.timeout --type int --value=30
qfg create my.price --type double --value=19.99
# Complex types
qfg create my.tags --type string-list --value="tag1,tag2,tag3"
qfg create my.config --type json --value='{"key": "value"}'
qfg create my.duration --type duration --value="PT30S"
# Encrypted values (secrets are always strings; prompts for the value, masked)
qfg create my.secret --secret
qfg create my.secret --secret --value-from-env MY_SECRET # read from a local env var
qfg create my.secret --secret --value-stdin < ./secret.txt # read from stdin
# Environment variable sourced
qfg create my.db.url --type string --env-var=DATABASE_URL
# Confidential (non-encrypted) values
qfg create my.api.key --type string --value="key123" --confidential
# Log level (key must start with `log-level.`; value is one of TRACE/DEBUG/INFO/WARN/ERROR/FATAL)
qfg create log-level.my-app --type log_level --value=INFO
Ways to pass the value (create and set-default; pick one):
--value=<v>— on the command line. Fine for ordinary values; for secrets it leaves the plaintext in shell history.--value-stdin— read from stdin, with one trailing newline stripped.--value-from-env <VAR>— copy the current value ofVARfrom your local shell, once. Fails ifVARis unset or empty.--env-var=<VAR>— store no value; your application readsVARfrom its own environment at runtime.- none of these —
qfgprompts for the value (masked for secrets).
Encryption vs Confidential:
--secret: Encrypts the value on your machine, requires the encryption key in your environment. Secrets are string-only, andcreate --secretdoes not ask for a type.--confidential: Marks value as sensitive but doesn't encrypt (useful for display purposes)--secretimplies--confidential, so you don't need both- Neither
createnorset-defaultprints a secret's value; they confirm with a redacted fingerprint. Details in Secret Management.
Inside a local-only workspace made by qfg init, create refuses to run unless you name the target with --workspace or QUONFIG_WORKSPACE; see init. The same goes for delete, set-default, set-rollout, log-level, override and activity restore.
Log levels: --type log_level requires the key to start with log-level. and the value to be a recognized level name (case-insensitive). --secret, --env-var, and --confidential are rejected on this type. To target individual loggers without creating one config per logger, write rules on the quonfig-sdk-logging.key context property — see log-level and Dynamic Log Levels.
log-level
qfg log-level NAME creates a log-level config, or adds a per-logger rule to one. The key must start with log-level..
It has two modes:
- Create (no
--target): creates the config with--valueas its default level. This is the same asqfg create NAME --type log_level. - Target loggers (
--target): adds a rule to an existing config that sets--valuefor every logger whose name starts with the given prefix. SDKs fill in thequonfig-sdk-logging.keycontext property from the logger name, and the rule matches it withPROP_STARTS_WITH_ONE_OF. The rule goes above the catch-all; if a rule with the same prefixes already exists, its level is replaced.
Options:
--value <level>-TRACE,DEBUG,INFO,WARN,ERRORorFATAL. In create mode it is the default level; with--targetit is required and is the level for the matched loggers.--target <prefix>- Logger name prefix. Repeat it to match any of several prefixes.--environment <env>- With--target, add the rule to this environment instead of the default rules. Without--targetit is an error; useqfg set-defaultto change an environment's level.
Examples:
# Create
qfg log-level log-level.my-app --value=WARN
# Turn one noisy package down everywhere
qfg log-level log-level.my-app --target=MyPackage.Noisy --value=ERROR
# Turn two packages up, in production only
qfg log-level log-level.my-app --target=A --target=B --value=DEBUG --environment=production
For anything more complex (regex, several criteria, exact matches), edit the config's JSON. Dynamic Log Levels explains how rules are evaluated and shows the stored JSON.
delete
qfg delete NAME deletes a flag, config or log level from the workspace. It removes the file and commits the change under your name; the earlier content stays in the workspace's git history, and qfg activity restore brings it back.
It asks you to type the key back to confirm. Pass --yes to skip that in scripts and CI.
qfg delete my.flag # type the key to confirm
qfg delete my.config --yes
environments
qfg environments (alias qfg envs) lists the environment names in your workspace and marks the protected ones. Pass one of these exact names to --environment (on set-default, set-rollout, get, run and so on). "[Default]" is not an environment: it names the default rules that every environment without rules of its own inherits.
qfg envs
qfg envs --json # {"environments": [{"id", "name", "protected"}]}
get
qfg get NAME evaluates a config and prints its value. Like the rest of the qfg commands that talk to your workspace, it authenticates with your qfg login session — not with an SDK key — so it is not tied to any one environment. You choose the environment per call with --environment.
In an interactive terminal, omitting --environment prompts you to pick one. Anywhere that is not an interactive terminal — a script, a CI job, a pipeline, or a $(...) command substitution — --environment is required, and leaving it off fails with 'environment' is required when interactive mode isn't available.
qfg get does not read QUONFIG_ENVIRONMENT, and neither does any other command that targets a workspace on your behalf. That variable tells a service which environment it is; the flag tells the CLI which environment to aim at. See Environment Variables.
Example:
qfg get aws.bucket --environment=production
For a secret, qfg get prints a redacted form (fingerprint, length, and the last 4 characters for values of 12 or more characters) and a hint, instead of the plaintext. Add --reveal to print the decrypted value:
qfg get my.api.key --environment=production # [encrypted *****3fa9c, 51 chars, ends …a1b2] (stdout; the note is on stderr)
qfg get my.api.key --environment=production --reveal # the plaintext
Don't use --reveal in a shared terminal, a CI log, or an AI agent session. See Checking a secret without revealing it.
Interpolating a value from Quonfig
Since the CLI is a well-behaved citizen of the command line, you can use it to compose other commands.
Here's an example command to download a file from s3 using the aws cli. Quonfig values are interpolated for the aws key and bucket name.
Note the explicit --environment on each call: inside $(...) the CLI's stdout is a pipe rather than a terminal, so it cannot prompt and will not guess an environment for you.
aws s3api get-object \
--bucket $(qfg get aws.bucket --environment=production) \
--key $(qfg get aws.db.backup.filename --environment=production) \
db.tgz
As you'd expect, you can similarly use qfg in a pipeline with xargs and similar.
Secrets are redacted here too, so $(qfg get my.api.key ...) expands to the redacted fingerprint, not the value. To hand a secret to another command, prefer qfg run, which puts it in the child's environment without printing it.
run
qfg run resolves Quonfig configs into environment variables and execs a child command. Use this for build steps, migrations, and any tool that reads its config from process.env before user code runs (and therefore can't call the SDK).
Example:
qfg run --env DATABASE_URL=db.url -- drizzle-kit migrate
qfg run --env-file=.qfg.env -- next build
The -- separator between qfg run flags and the child command is required. Auth/environment is binary — set either QUONFIG_BACKEND_SDK_KEY (Mode A) or use qfg login plus --environment / QUONFIG_ENVIRONMENT (Mode B), never both. See Running commands with injected env for the full reference, package.json patterns, and the instrumentation.ts comparison.
sdk-key
qfg sdk-key creates, lists and revokes the SDK keys your applications use.
qfg sdk-key create --name <name>- Create a key.--name(-n) is required; name it after what uses the key.--environment(-e) picks the environment and--type(-t) isserver(backend SDKs) orbrowser(frontend SDKs); leave either off to be prompted.qfg sdk-key list- List keys, optionally filtered with--environment.qfg sdk-key revoke <key-id>- Revoke a key by the ID thatlistshows.
qfg sdk-key create --name "checkout service" --environment production --type server
qfg sdk-key create --name "marketing site" --environment staging --type browser
qfg sdk-key list --environment production
qfg sdk-key revoke a1b2c3d4-e5f6-7890-abcd-ef1234567890
activity
qfg activity shows what changed in the workspace.
qfg activity feed- Recent changes across the workspace, newest first: who changed which key, and how.--limitsets how many (1-100, default 30).qfg activity history NAME- The full change history of one flag, config, log level, segment or schema.qfg activity deleted- Keys that were deleted and not restored.qfg activity restore NAME- Bring back a deleted key from its last content. It shows who deleted it and when, then asks to confirm (--yesskips that).--typeis inferred when omitted. Schemas can't be restored this way; use git history.
qfg activity feed --limit 5
qfg activity history my.flag
qfg activity deleted
qfg activity restore my.flag --yes
agent install-skill
qfg agent install-skill installs the Quonfig agent skill into an application repo, so coding agents use the SDK, qfg and the MCP tools correctly. It writes .claude/skills/quonfig/, which Claude Code picks up automatically. The files are the same as claude plugin install quonfig@quonfig from github.com/quonfig/skills, bundled into the CLI so nothing is downloaded.
Options:
--add-pointer- Also add a one-line pointer to the skill in./AGENTS.md, for Codex, Cursor and other agents that read it--dir <path>- Install into a different skills directory (for example.agents/skills)--force- Overwrite skill files you've edited
Re-running it upgrades the files it wrote earlier. If you've edited one, it stops and lists the file unless you pass --force.
qfg agent install-skill --add-pointer
This skill is for application repos. A workspace made by qfg init already has its own AGENTS.md and CLAUDE.md.
Your workspace's main is append-only
Every workspace is a git repo. Clone it with qfg pull and publish your commits
with qfg push. Every push to main has to fast-forward from the current tip.
A force-push, deleting main, or creating main by push is rejected by the
server with a message that says what to do instead.
The reason: config delivery follows main forward. A rewritten main cannot be
fast-forwarded by the delivery servers, and connected SDKs ignore a snapshot whose
generation is not newer than the one they hold, so a force-push does not roll
anything back for your users; it silently freezes what they receive. A forward
commit does what a force-push was meant to do, and the next section shows how.
If a push is rejected because someone else pushed first, pull and rebase, then push again:
qfg pull --rebase && qfg push
Updating a branch other than main
qfg push publishes whichever branch you have checked out. To bring a branch up
to date with main, merge main into it and push:
git fetch origin
git merge origin/main
qfg push
Rewriting a branch that is already on the server (a rebase or a force-push) is
not supported yet. Merge main in instead.
If the rejection came from qfg workspace bootstrap on an older CLI, upgrade the
CLI (npm install -g @quonfig/cli@latest); current versions never force-push.
Rolling the whole workspace back to an earlier commit
Something landed that shouldn't have — a bad bulk edit, a script that rewrote more
than you meant, a merge that went sideways. Your workspace is a git repo, so every
earlier state is still there, and you go back to one by committing it forward:
a new commit whose content is the old content. Your workspace's main is
append-only, so nothing here rewrites history.
Find the commit you want (qfg activity feed, or git log in your local checkout),
then from a local checkout of the workspace:
qfg pull # start from what the workspace has right now
git restore --source=<sha> --staged --worktree -- . # put every file back to how it was at <sha>
git commit -m "restore <sha>"
qfg push
That publishes one new commit on top of the current history whose files are exactly
the files from <sha> — your SDKs pick it up like any other push, and the commits in
between stay in the history as a record of what happened.
Do not use git checkout <sha> -- . for this. It overlays the files that existed
at <sha> and never deletes anything, so every flag or config added after <sha>
survives and keeps being served — you get a mix of the two states, not the state you
asked for. git restore --staged --worktree -- . removes those files too, which is
what "put the workspace back how it was" actually means.
To bring back a single flag or config that was deleted, run
qfg activity restore <key> instead — this recipe is for putting the whole
workspace back.
Troubleshooting
Common Issues
Authentication Problems:
# Clear authentication and re-login
qfg logout
qfg login
# Check who you're logged in as and which workspace is the default
qfg whoami
qfg workspace
Configuration Generation Issues:
# Generate with verbose output to see detailed logs
qfg generate --verbose
# Check if config file exists and is valid JSON
cat quonfig.config.json | jq .
Network/API Issues:
# Test connectivity with verbose output
qfg list --verbose
# Check whether the API host has been overridden
echo $QUONFIG_DOMAIN $QUONFIG_API_BASE_URL_OVERRIDE
Environment Variables
QUONFIG_API_KEY- Authenticate with an API key instead of aqfg loginsession — for CI and scripts. Either a personal key (qf_uk_...) or a service-account key (qf_sa_...); mint both in the app, see REST API authentication. When set, the workspace must also be named, withQUONFIG_WORKSPACEor--workspace.QUONFIG_WORKSPACE- The workspace to act on, overriding your saved default (--workspacewins over it). Required whenQUONFIG_API_KEYis set:<org>/<workspace>(e.g.acme/production) or the workspace's UUID. Service-account keys must use the UUID —qf_sa_principals have no user-level workspace list, so anorg/workspaceslug fails withNo workspace matching ... Available: (none). Find the UUID withGET /v1/whoamiusing the same key (it returnsworkspaceId), or read it from the app's URL — every workspace page is/workspaces/<uuid>/....QUONFIG_DOMAIN- The base domain the CLI derives its API host from (defaultquonfig.com, givinghttps://app.quonfig.com)QUONFIG_API_BASE_URL_OVERRIDE- Full API base URL; wins overQUONFIG_DOMAINQUONFIG_DIR- Default local directory forpull,push,generateandserve(avoids repeating--dir)QUONFIG_ENVIRONMENT- Read only by the two commands that run as a service:qfg serve(flag, then the variable, thendevelopment) andqfg run. Every operator command that reads or writes a workspace (get,set-default,set-rollout,override,log-level, ...) ignores it and takes--environment(or--envforoverride) explicitly. The rule: the variable tells a service what it is; the flag tells the CLI what to aim at. An ambient variable must never choose where a write lands.NO_COLOR- Disable colored output