Skip to main content

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.

Need env vars in a build or migration step?

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). Overrides QUONFIG_WORKSPACE and 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/JavaScript
  • quonfig-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.js
  • quonfig-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 verify hook
  • The workspace directory layout: configs/, feature-flags/, segments/, log-levels/, schemas/
  • A quonfig.json describing the workspace and its environments
  • A managed README.md, CLAUDE.md, and AGENTS.md that 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 in quonfig.json (only matters if you later run qfg push against 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 key field
  • 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 to QUONFIG_DIR, then the nearest directory at or above the current one that has a quonfig.json)
  • --workspace <id> (-w) - Workspace to pull (defaults to your saved default workspace)
  • --rebase - When your local commits and the workspace's main have diverged, replay your commits on top of main. Without it, qfg pull stops 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 to QUONFIG_DIR, then the nearest directory at or above the current one that has a quonfig.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 push pushes what you have already committed and ignores this flag.
  • --no-pin-write - Don't offer to write the workspace pin into quonfig.json after 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).

CommandWhat it does
qfg cr listList 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 merge refuses 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 serve uses QUONFIG_DIR, then ./our-config, then ./.quonfig (relative to the current directory; it does not search parent directories the way pull and push do)
  • --environment <slug> - Environment to evaluate. The flag wins; otherwise QUONFIG_ENVIRONMENT; otherwise development. qfg serve hosts a service, so it reads the variable the same way an SDK does (see Environment Variables).
  • --port <n> - TCP port (default 6580)
  • --host <addr> - Bind address (default 127.0.0.1; non-loopback requires --allow-non-loopback)
  • --frontend-sdk-key <key> - If set, require Authorization: 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 a quonfig.json, generate uses 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 --workspace is given (or active credentials are set), generate mints 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 to QUONFIG_DIR env var). When unset, generate walks up from cwd looking for quonfig.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 if QUONFIG_API_KEY is set without QUONFIG_WORKSPACE. Passing --workspace skips the cwd auto-detect and goes straight to the API path.
  • --targets <targets> - Specify target platforms: react-ts (default) or node-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.ts files) 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
info

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>.

Profiles are deprecated

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

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 days
  • LAST_EVAL - the most recent day with any evaluations
  • CLASS - quiet (no evaluations in the last 2 days) or active
  • KIND and MARKED - shown with --all only

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 override never reads QUONFIG_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 / canaryqfg set-rollout
Set one value for EVERYONE, deleting that environment's targeting rulesqfg set-default --replace-targeting
Target specific customers or users, a plan, a segment, or any custom propertyEdit 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.json to 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:

  1. QUONFIG_WORKSPACE, if set (<org>/<workspace>, or the workspace UUID).
  2. The workspace pin in <dir>/quonfig.json, if the directory has one.
  3. Your saved default workspace (shown by qfg workspace, changed with qfg 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 of VAR from your local shell, once. Fails if VAR is unset or empty.
  • --env-var=<VAR> — store no value; your application reads VAR from its own environment at runtime.
  • none of these — qfg prompts 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, and create --secret does not ask for a type.
  • --confidential: Marks value as sensitive but doesn't encrypt (useful for display purposes)
  • --secret implies --confidential, so you don't need both
  • Neither create nor set-default prints 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:

  1. Create (no --target): creates the config with --value as its default level. This is the same as qfg create NAME --type log_level.
  2. Target loggers (--target): adds a rule to an existing config that sets --value for every logger whose name starts with the given prefix. SDKs fill in the quonfig-sdk-logging.key context property from the logger name, and the rule matches it with PROP_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, ERROR or FATAL. In create mode it is the default level; with --target it 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 --target it is an error; use qfg set-default to 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) is server (backend SDKs) or browser (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 that list shows.
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. --limit sets 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 (--yes skips that). --type is 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 a qfg login session — 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, with QUONFIG_WORKSPACE or --workspace.
  • QUONFIG_WORKSPACE - The workspace to act on, overriding your saved default (--workspace wins over it). Required when QUONFIG_API_KEY is 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 an org/workspace slug fails with No workspace matching ... Available: (none). Find the UUID with GET /v1/whoami using the same key (it returns workspaceId), 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 (default quonfig.com, giving https://app.quonfig.com)
  • QUONFIG_API_BASE_URL_OVERRIDE - Full API base URL; wins over QUONFIG_DOMAIN
  • QUONFIG_DIR - Default local directory for pull, push, generate and serve (avoids repeating --dir)
  • QUONFIG_ENVIRONMENT - Read only by the two commands that run as a service: qfg serve (flag, then the variable, then development) and qfg run. Every operator command that reads or writes a workspace (get, set-default, set-rollout, override, log-level, ...) ignores it and takes --environment (or --env for override) 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