Integrations

CLI

Find where your code reads each config, fail the build when it reads a key that does not exist, was renamed, or has the wrong type, see the value a context gets for a config and why, read a project's configs and targeting rules, create configs, replace a config's targeting rules, archive configs, read an experiment's results, and create, update and delete segments and metrics, with the configdirector command line tool

Introduction

Commands and their output may change before 1.0, and the changelog lists every change.

configdirector checks your code against your ConfigDirector project, on your machine or as a CI step, and answers what a context gets for a config. Besides login, logout and init, which set it up, it has three commands:

  • configdirector scan lists every place your code reads a config key through a ConfigDirector SDK or OpenFeature provider, with the file and line.
  • configdirector validate checks those keys against the project's configs, and fails the build when the code reads a key no config has, the old key of a renamed config, a config as the wrong type, a config that is not served to that kind of SDK, or an enum value the config does not allow.
  • configdirector evaluate shows the value a context gets for a config in an environment, the rule that served it, and why each rule matched or not.

It also lists a project's environments, configs and segments, and shows a config's targeting rules and when SDKs last evaluated it, as Browse the project describes, and it creates and copies configs, replaces their targeting rules and archives them, as Create a config, Copy a config, Targeting rules and Archive a config describe, lists an experiment's runs with their results and ships or stops them, as Experiment runs describes, and creates, updates and deletes segments and metrics, as Segments and Metrics describe. scan --upload sends the scan to the project, as Upload the scan to ConfigDirector describes, and repositories list and repositories remove list and remove the repositories uploaded to it, as Scanned repositories describes. configs create, configs copy, targeting-rules set, configs ship, configs stop, configs archive, segments create, segments update, segments delete, metrics create, metrics update, metrics delete, scan --upload and repositories remove are the only commands that change anything in ConfigDirector.

If you have used LaunchDarkly's ld-find-code-refs or ConfigCat's configcat scan: those tools search your code for the keys your flags already have. scan also lists the SDK calls whose key no config has, which is how validate catches a misspelled key before it ships. A key held in a constant is found too, with nothing to configure.

Install

The CLI needs Node.js 20 or later. Install it globally:

npm install -g @configdirector/cli
configdirector --version

Or run it without installing by writing npx @configdirector/cli in place of configdirector, as the CI examples do:

npx @configdirector/cli --version

Both get the newest release. To upgrade on your own schedule, add a version number from the changelog, as in @configdirector/cli@0.11.0. If you installed @configdirector/cli@beta before 0.11.0, install it again without @beta, which stays on the last beta.

Or install it with Homebrew, which takes care of Node.js:

brew install ConfigDirector/tap/configdirector
configdirector --version

The Homebrew formula is updated with every npm release, so brew upgrade configdirector gets the newest one.

Create an API token

The CLI reads your projects and configs through the Admin API, with an API token.

  1. In the ConfigDirector dashboard, open API tokens and create a token.
  2. Choose Projects: Read and Configs: Read, which scan and validate need. For evaluate, add Environments: Read, and Contexts: Read to evaluate a config for a saved context. To browse the project, add Environments: Read for environments list, Segments: Read for segments list and segments get, Metrics: Read for metrics list and metrics get, Tags: Read for configs list --tag, and Code references: Read (code-references:read) for repositories list. A token with only these permissions cannot change anything. To create configs, add Configs: Create, with Tags: Read for configs create --tag and Tags: Create for configs create --new-tag. To copy configs, add Configs: Create, with Tags: Create to create the tags another project doesn't have. To replace targeting rules, add Environments: Read and Configs: Update targeting rules (config-targeting-rules:update). To list an experiment's runs, add Environments: Read, and to ship a variation or stop a run, add Configs: Update targeting rules as well. To archive configs, add Configs: Archive (configs:archive). To create, update and delete segments, add Segments: Create, Segments: Update and Segments: Delete (segments:create, segments:update and segments:delete), with Segments: Read for segments update. To create, update and delete metrics, add Metrics: Create, Metrics: Update and Metrics: Delete (metrics:create, metrics:update and metrics:delete), with Metrics: Read for metrics update and metrics delete. To upload the scan or remove a scanned repository, add Code references: Update (code-references:update).
  3. Set an expiration on a token you keep on your workstation, and do not commit a token into source control.

A token belongs to the member who created it, and it stops working when that member leaves the organization. For CI, create a token used only by CI rather than reusing the one on your workstation, so you can replace or revoke it without affecting anything else. If its creator leaves, CI fails with API_TOKEN_OWNER_REMOVED until another member creates a new one.

Configure

Sign in on your machine

configdirector login

login asks you to paste the token and hides it while you do. It asks ConfigDirector which organization the token belongs to and what it can do, refuses a token without Projects: Read, and saves it as your sign-in for that organization, with the organization's name, where only your user can read it:

SystemSaved in
macOS~/Library/Application Support/configdirector/sign-ins.json
Linux~/.config/configdirector/sign-ins.json
Windows%APPDATA%\configdirector\sign-ins.json

When XDG_CONFIG_HOME is set, the sign-ins are saved in $XDG_CONFIG_HOME/configdirector/sign-ins.json instead. configdirector login --token <token> saves a sign-in without asking.

You keep one sign-in per organization. Running login again with a token of an organization you are signed in to replaces that sign-in, and with a token of another organization adds one, so you can work for two organizations from one machine, as More than one organization describes. configdirector logout removes the sign-in the commands in the current directory would use; the token itself keeps working until you revoke it on the API tokens page.

Versions before 0.10.0-beta.1 saved one token in config.json in the same directory. The first command you run after upgrading moves that token into a sign-in, with one request to learn its organization, and deletes config.json. A token ConfigDirector no longer accepts is deleted without becoming a sign-in, and the command says so; when the Admin API cannot be reached, config.json stays for the next run.

In CI, skip login and set CONFIGDIRECTOR_TOKEN. The CLI uses --token first, then CONFIGDIRECTOR_TOKEN, then the sign-in for the organization the repository names, then your only sign-in. configdirector api-token get shows which token a command in the current directory would use, with its organization, name, permissions and expiration, as Browse the project describes.

From the repository root, with your project's slug, shown as Project slug on the project's Project details page:

configdirector init --project web-app

init looks for the project through each of your sign-ins, or through the token you give it, and writes configdirector.json in the current directory with the project's slug and the id of its organization. It never overwrites an existing file, except to add organization to a file from an earlier version that has none, keeping its other fields. Commit the file, so every run and every CI job uses the same project, and run the CLI from the directory that holds it.

configdirector.json
{
  "project": "web-app",
  "organization": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "include": ["src/**"],
  "exclude": ["src/generated/**"],
  "ignoreKeys": ["billing-flag-from-other-project"]
}
FieldMeaning
projectThe project's slug. --project and CONFIGDIRECTOR_PROJECT take precedence over it.
organizationThe id of the project's organization. A command in the directory uses your sign-in for it, and refuses a token of another organization, such as a CONFIGDIRECTOR_TOKEN set for an MCP server, when that organization has a project with the same slug. --organization and CONFIGDIRECTOR_ORGANIZATION take precedence over it.
includeGlobs of the files to scan, relative to configdirector.json. init writes ["**"], every file.
excludeGlobs of the files to skip, on top of the files the scan always skips.
ignoreKeysKeys that validate never reports, such as the key of a config another project serves.

More than one organization

A project's slug is unique within its organization, so two organizations can each have a web-app. With one sign-in per organization and the organization's id in each repository's configdirector.json, every command uses the right token without a variable per directory. Sign in once per organization, with a token of each:

configdirector login   # paste a token of Acme
configdirector login   # paste a token of Globex

Then run init in each repository. It looks for the project through both sign-ins and writes the organization that has it:

cd ~/code/acme-storefront
configdirector init --project web-app
# Linked this directory to the project Web App (web-app) of the organization Acme in .../configdirector.json

cd ~/code/globex-portal
configdirector init --project web-app
# Linked this directory to the project Web App (web-app) of the organization Globex in .../configdirector.json

From then on, a command in either repository uses that organization's sign-in. When both organizations have a project with the slug, init stops and asks you to name one with --organization, by the organization's name as login saved it, whatever its case, or by its id. --organization and CONFIGDIRECTOR_ORGANIZATION also pick the sign-in for a command run outside a linked repository, such as projects list; a command run with two sign-ins and no organization named stops and lists them.

A token you pass with --token or CONFIGDIRECTOR_TOKEN is always used as it is, so a CONFIGDIRECTOR_TOKEN set for every terminal, for example for an MCP server, takes precedence over your sign-ins. In a repository that names another organization, the command then stops before changing anything and names the variable, as long as that organization has a project with the same slug. Give the MCP server a variable named for its organization instead, and leave CONFIGDIRECTOR_TOKEN unset.

Options and environment variables

Every command takes these options, as well as --help and --version:

OptionEnvironment variableMeaning
--token <token>CONFIGDIRECTOR_TOKENThe API token. Without either, the sign-in saved by login for the organization named below, or your only sign-in.
--organization <name or id>CONFIGDIRECTOR_ORGANIZATIONThe organization whose sign-in to use, by the name login saved or by its id. Without either, the organization in configdirector.json. Giving one together with --token or CONFIGDIRECTOR_TOKEN is a mistake, and the command exits with 2.
--project <slug>CONFIGDIRECTOR_PROJECTThe project's slug. Without either, every command that reads a project uses the project in configdirector.json. projects list and targeting-rules reference ignore all three.
--base-url <url>CONFIGDIRECTOR_BASE_URLThe Admin API host. Defaults to https://api.configdirector.com.
--jsonPrint JSON instead of text. See Output.

An option takes precedence over its environment variable. An empty variable counts as unset, so a CI job whose token secret is missing stops with No API token found rather than sending an empty token.

Scan

configdirector scan

scan lists every place your code reads a config key, grouped by key, with the file, the line, the SDK call and the SDK:

max-cart-items
  src/admin/feature-list.ts:1 (indirect)
  src/checkout.ts:6 getValue (js-server)

new-checkout
  src/admin/feature-list.ts:1 (indirect)
  src/checkout.ts:5 getValue(NEW_CHECKOUT) (js-server)
  test/checkout.test.ts:3 createTestClient (js-server, test)

Dynamic references (calls whose key is not a string literal)
  src/settings.ts:3 getValue(setting.key) (js-server)

3 direct, 2 indirect and 1 dynamic references in 5 scanned files.

Each place is one of three kinds of code reference:

  • Direct: an SDK call whose key is known, either a string such as getValue("max-cart-items", 20) or a constant that holds one, shown after the call as getValue(NEW_CHECKOUT). These are the references validate checks.
  • Indirect: one of the project's keys written as a quoted string anywhere else, such as a list of keys, the argument of your own wrapper function, or a test fixture. The key is used there, but not through a call validate can check, so look at these before you rename or archive the config.
  • Dynamic: an SDK call whose key cannot be known from the code, such as a variable, a key built at runtime, or a constant assigned a different string in two places. These are listed so you know they exist. They are never checked, so they never fail the build; to have one checked, pass the key as a string or a constant.

A reference is marked test when it is a call to an SDK test client, such as createTestClient or setValue, or an indirect reference in a test directory or a test file such as checkout.test.ts.

The scan exits with 0 whenever it ran, whether it found references or not. configdirector scan src scans only src.

What the scan reads

A call is found when its file imports a ConfigDirector SDK or the OpenFeature SDK. In JavaScript, TypeScript, Python, Dart and Go, it is also found when the file imports one of your own files that does, such as the setup module the SDK pages create. In Kotlin, Java and C#, it is also found when the file uses a class of your own that holds the client, such as object Flags, in a file named after the class (Flags.kt, Flags.java or Flags.cs) that imports the SDK. In Swift and Go, it is enough for another file of the same target or package to import the SDK, and Nuxt's auto-imported composables need no import. A getValue from another library in a file that imports none of these is not reported.

The scan skips the files .gitignore ignores, the node_modules, vendor, build, dist and target directories, binary files, and files over 1 MB. include and exclude in configdirector.json narrow it further.

If a call you expected is missing, the file most likely reaches the SDK client in one of these ways:

  • Through two of your own files, such as a module that imports the setup module and passes the client on. Import the setup module directly, or have the module in between re-export the client with export { client } from "./setup".
  • Through a path alias that only your bundler knows, such as resolve.alias in vite.config.ts. Add the alias to compilerOptions.paths in tsconfig.json.
  • Through a CommonJS re-export, such as module.exports = require("./setup").
  • In Kotlin, Java or C#, through a class of your own declared in a file with another name, such as an object Flags inside ConfigDirectorSetup.kt, or through a class that gets the client from another class of yours. Move the class that holds the client into a file named after it, or declare the client with its SDK type, such as a ConfigDirectorClient parameter or property, so the file names the SDK.
  • In Kotlin, through a client declared at the top level of a file, outside any object or class. Declare it in an object, such as object Flags.
  • In Kotlin or Java, through a class of another source directory or module, such as a test in src/test/java using a class of src/main/java. Declare the client with its SDK type in the file that calls it.
  • In Kotlin or Java, through an import in a file whose directory does not match its package, such as package com.example.web in src/main/kotlin/web/. Classes in the file's own directory are still found.
  • In C#, in a file with no .csproj in its directory or above it, up to the directory the scan runs in.

Snippets

With --json or --upload, each direct and indirect reference comes with a snippet: its line and the 2 lines before and after it, so ConfigDirector can show the code around the reference without opening the repository. The text output shows no snippets, and dynamic references have none.

configdirector scan --json --context-lines 4

--context-lines <number> sets how many lines before and after the reference to include, from 0 to 5, and --context-lines 0 includes the reference line alone. A snippet stops at the start and end of the file, and a line longer than 250 characters is cut to its first 250. --no-snippets leaves every snippet out. Giving both, or a --context-lines that is not a whole number from 0 to 5, exits with 2.

Upload the scan to ConfigDirector

configdirector scan --upload

--upload sends the scan to your project, so the dashboard can show where each config is read and which configs no repository reads. ConfigDirector keeps the latest scan of each repository: every upload replaces all the references the project held for that repository, so a reference you remove from the code is gone after the next upload.

Upload from your default branch, after each push to it. scan --upload does not check which branch is checked out, so an upload from a feature branch replaces the default branch's references with that branch's. Keep validate for pull requests. On GitHub, the ConfigDirector Code Scan action does both: it runs validate on pull requests and uploads only on pushes to the default branch.

On GitLab, add a job that runs only on the default branch:

.gitlab-ci.yml
configdirector-upload:
  image: node:24
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  script:
    - npx --yes @configdirector/cli scan --upload

The repository is named after the path of its origin remote, without the host and .git: https://github.com/acme/shop.git, git@github.com:acme/shop.git and ssh://git@github.com/acme/shop.git all upload to acme/shop, and a GitLab project in a subgroup keeps its whole path, such as group/subgroup/app. The upload also sends the remote's URL and the SHA of the commit that is checked out, which the CLI reads by running git. A user name and password in an https remote, such as the job token GitLab CI puts there, are removed before the URL is sent.

--repository <name> names the repository yourself, for a clone whose origin points somewhere else or a directory that is not a git repository. Without it, scan --upload exits with 2 when git is not installed, when the directory is not in a git repository, or when that repository has no origin remote. With it, each of those cases uploads with no remote URL and no commit. A repository with no commit yet uploads with no commit.

The scan's output ends with what was uploaded:

new-checkout
  src/checkout.ts:5 getValue(NEW_CHECKOUT) (js-server)

1 direct, 0 indirect and 0 dynamic references in 3 scanned files.

Uploaded the scan of acme/shop at 4d40f50 to web-app: 1 reference and 0 dynamic references, with 0 left out for a key that cannot be a config key.

The upload holds the direct, indirect and dynamic references that scan --json prints; ignoreKeys changes nothing in it. A reference to a key that cannot be a config key, such as one shorter than 4 characters, is left out and counted on that last line. When the scan finds no source file, scan --upload exits with 2 and uploads nothing, so a wrong path or include never empties the repository's references. A scan that reads files and finds no reference is uploaded, and the repository then has no references. With --json, scan --upload prints the Admin API's response as received, the scanned repository with its reference counts, in place of the scan.

A project holds at most 50 scanned repositories, and one upload holds at most 10,000 references, dynamic references included. Uploading another repository to a project that holds 50, or a larger scan, exits with 2.

scan --upload needs Projects: Read, Configs: Read and Code references: Update (code-references:update), and makes three Admin API requests. Uploads do not appear in the audit log.

What leaves your repository

An upload sends ConfigDirector:

  • the path of each file with a reference, from the directory the scan ran in, and the line of each reference;
  • the config keys the code reads;
  • for each SDK call, the SDK, the call's name, the key argument as written when it is not a plain string, and the in-code default value when it is a literal;
  • whether each reference is in a test;
  • the snippet of each direct and indirect reference: at most 11 lines of code, the reference line and up to 5 lines on each side, each cut to 250 characters;
  • how many files the scan read;
  • the URL of the origin remote, without the user name and password of an https remote;
  • the SHA of the commit that is checked out, without its changes, author or message.

Nothing else from the repository is sent.

To send no code, add --no-snippets: the upload then sends everything above but the snippets. To keep a project from storing any code, an owner or an admin can turn off Store code snippets in the Code snippets card of the project's Project details page. The project then removes the snippets it holds, and scan --upload sends none and says so after what it uploaded:

Uploaded the scan of acme/shop at 4d40f50 to web-app: 1 reference and 0 dynamic references, with 0 left out for a key that cannot be a config key.
Code snippets were not sent: this project does not store them.

If the setting is turned off while scan --upload runs, the upload still succeeds, and the project stores it without its snippets.

Scanned repositories

ConfigDirector keeps the latest upload of every repository that ran scan --upload, and nothing removes one on its own. A repository that is renamed or retired keeps its last upload, keeps counting toward the 50 a project can hold, and its references still count when the dashboard shows where each config is read and which configs no repository reads. These commands list a project's scanned repositories and remove one.

configdirector repositories list

repositories list prints a header row, then one line per repository, with the commit of its latest upload, when it was scanned in UTC, and how many references and dynamic references it holds, and ends with how many scanned repositories the project has out of the 50 it can hold:

REPOSITORY           COMMIT    SCANNED                REFERENCES      DYNAMIC REFERENCES
ConfigDirector/cli   4d40f50   2026-10-17 10:00 UTC   12 references   1 dynamic reference
acme/storefront      9f3e2a1   2026-10-16 09:12 UTC   1 reference     0 dynamic references

web-app has 2 of the 50 scanned repositories a project can hold.

A repository uploaded without a commit shows no commit, and --no-headers leaves out the header row. With --json, it prints the Admin API's response as received: the scanned repositories, which also give each one's remote URL and how many files its scan read.

configdirector repositories remove acme/storefront

repositories remove removes the repository and all its references from the project, with no confirmation:

Removed acme/storefront and its code references from web-app.

A removed repository that uploads again is added back, so remove the upload step from its CI first. To rename a repository, remove the old name and upload under the new one.

repositories remove exits with 0 when it removed the repository, and with 2 when no scanned repository in the project has the name, listing the names the project has. With --json, it prints { "removedRepository": "acme/storefront" }, with the name as you gave it, since the Admin API answers with no body.

repositories list needs Projects: Read and Code references: Read (code-references:read). repositories remove needs Projects: Read and Code references: Update (code-references:update), and Code references: Read to list the names when none matches. Each makes two Admin API requests, and repositories remove one more when no repository has the name. Removals do not appear in the audit log.

Validate

configdirector validate

validate runs the same scan, then checks every direct reference against the project's configs. It lists the problems it found by kind, and exits with 1 when there is at least one:

Unknown keys
  src/checkout.ts:9 free-shiping: no config in web-app has this key.

Deprecated keys
  src/checkout.ts:6 checkout-v2: the config was renamed to new-checkout.

Type mismatches
  src/checkout.ts:8 checkout-timeout: read as string, but the config's type is timespan, served as a float.

Availability mismatches
  src/theme.tsx:4 fraud-threshold: read from a client SDK (react), but the config is server-only.

Enum values not allowed
  src/theme.tsx:3 theme: "system" is not one of the allowed values: light, dark.

Checked 7 direct references in 4 scanned files and found 5 problems. 1 dynamic reference was not checked.
ProblemWhat it means for your appWhat to do
Unknown keysNo config in the project has this key, as its current key or an old one, so the SDK returns the in-code default value every time. The key of an archived config is unknown too.Correct the key, or create the config. If another project serves the key, add it to ignoreKeys.
Deprecated keysThe config was renamed, and the code still reads an old key. The old key works until ConfigDirector removes it once it is no longer used, as Key explains.Replace it with the current key, which the output names.
Type mismatchesThe in-code default value, or a getter whose name sets the type such as getBoolean, reads the config as a type the SDKs do not serve it as, so the SDK can return the in-code default value instead of the config's value.Read the config as the type the output names.
Availability mismatchesA client SDK reads a server-only config, or a server SDK reads a client-only one. That SDK never receives the config, so it returns the in-code default value every time.Change the config's SDK availability, or read the config where it is served.
Enum values not allowedThe in-code default value is not one of the enum's allowed values.Use an allowed value as the in-code default value, or add the value to the enum.

The SDKs serve a timespan as a number in its unit and a URL as a string. So an in-code default value, or a getter whose name sets the type, reads a config of these types: a boolean reads a boolean config; an integer reads an integer, float or timespan config; a decimal number reads a float or timespan config; a string reads a string, enum or URL config; and an object or array reads a JSON config. Read a timespan with a number, not a string such as "30s". An enum whose values are numbers can also be read with a number.

A test client call is checked for unknown and deprecated keys only, since ConfigDirector never serves a test client. Indirect and dynamic references are never checked, and a config's lifecycle state is never a problem.

Exit codes

CodeMeaning
0The command succeeded. For validate, it found no problem.
1validate found at least one problem, or configs create found a config that already has the key.
2The command could not run: a mistake in the command, no token or a rejected one, a token of another organization than the repository's, a missing permission, a suspended service, an unreachable API, or something the command names that does not exist, such as a config key, an environment, a saved context, a segment key, a tag or a scanned repository. segments delete also exits with 2 when the targeting rules of a config use the segment. metrics get, metrics update and metrics delete also exit with 2 when several metrics have the event name they are given. The message says which.

A CI job can therefore tell a wrong config key from an outage.

Run it in CI

Add the token as a secret named CONFIGDIRECTOR_TOKEN. On GitHub, the ConfigDirector Code Scan action runs validate and uploads the scan. On GitLab and other CI systems, run the CLI with npx.

GitHub Actions

Add the secret under the repository's Settings → Secrets and variables → Actions, and add this workflow, or its last step to an existing job that checks out the code:

.github/workflows/configdirector.yml
name: ConfigDirector

on:
  pull_request:
  push:
    branches: [main]

jobs:
  configdirector:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: ConfigDirector/scan-code@v1
        with:
          token: ${{ secrets.CONFIGDIRECTOR_TOKEN }}

On a pull request, the action runs validate. On a push to the repository's default branch, it runs validate and then scan --upload, so the dashboard shows where each config is read. It uploads even when validate found a problem, so the dashboard shows the code as it is, and the job still fails.

validate needs Projects: Read and Configs: Read, and the upload also needs Code references: Update. With upload: false, the action never uploads, and a token with only the two read permissions is enough.

InputDefaultWhat it does
tokenRequired. The API token, from a secret.
versionlatestThe version of @configdirector/cli to run, or an npm dist-tag. A version number from the changelog, 0.9.0-beta.1 or later, upgrades on your own schedule.
working-directory.The directory that holds configdirector.json. The scan reads the files under it.
uploadautoWhen the scan is uploaded: auto on pushes to the default branch only, true on every run, false never.
context-lines2How many lines before and after each reference its snippet holds, from 0 to 5.
snippetstruefalse uploads no code, as --no-snippets does.

The action sets up Node.js 24, and the steps after it in the same job run with that Node.js too, so in a job that sets up another version, put the action after the steps that need it. The action's README also covers pull requests from forks, which GitHub runs without your secrets.

GitLab

Add the token as a masked variable under the project's Settings → CI/CD → Variables, which GitLab passes to every job as an environment variable, and add this job to .gitlab-ci.yml. A variable marked Protect variable reaches only pipelines of protected branches and tags, so leave it unmarked for the check to run on merge requests.

.gitlab-ci.yml
configdirector-validate:
  image: node:24
  script:
    - npx --yes @configdirector/cli validate

To upload the scan from GitLab too, add the job in Upload the scan to ConfigDirector.

Other CI systems

Run npx --yes @configdirector/cli validate with Node.js 20 or later and CONFIGDIRECTOR_TOKEN set, for every change, and npx --yes @configdirector/cli scan --upload after each push to the default branch.

Each scan or validate run makes two Admin API requests, scan --upload makes three, login makes one, and init makes one per sign-in it searches; the first command run after upgrading to 0.10.0-beta.1 makes one more, to move the token an earlier version saved. The GitHub action makes two on a pull request and five on a push to the default branch. They count toward your organization's monthly free allowance like any other Admin API request.

Evaluate

configdirector evaluate new-checkout --environment production --context-id 123 --context-trait plan=pro

evaluate shows the value a context gets for a config in one environment, and why. It evaluates the environment's saved targeting rules with the same evaluator the SDKs use, so the value is the one your application would get:

new-checkout in Production for user 123

true, served by rule 2

1. 50% get true                     not matched: bucket 71.3 is outside 0 to 50
2. plan is one of pro, team: true   matched
3. in segment Beta testers: true    not evaluated
Default targeting rule: false

The first line names the config, the environment and the context. The next gives the value and the rule that served it, or the default targeting rule when no rule matched. Then comes each targeting rule in order, with what it tests, the value it serves, and its outcome:

OutcomeWhat it means
matchedThe context meets every condition of the rule, and for a percentage rollout, its bucket falls in a share. The value comes from this rule.
not matchedThe rule does not apply to the context. The output names the first condition that failed and the context's value for it, such as plan is one of pro, team, but it is "free", or the bucket the context fell in outside the rule's shares.
rollout skippedThe context reached a percentage rollout, either a percentage rule or the rollout a conditional rule serves once its conditions are met, and it has no identifier, so it has no bucket. The line reads rollout skipped: the context has no identifier, and the rules after it are tried; the context gets the default targeting rule value when none of them applies.
not evaluatedAn earlier rule served the value, so this rule was not checked.
erroredThe rule could not be evaluated, so it was skipped, as an SDK skips it.

A percentage rollout gives each context a bucket from 0 to 100, worked out from the config, the context kind and the identifier, so a context keeps its bucket from one evaluation to the next. A context without an identifier gets no bucket: a percentage rollout it reaches is skipped and shows as rollout skipped: the context has no identifier, the rules after it are tried and show their own outcomes, and the context gets the default targeting rule value when none of them applies. Versions before 0.20.0 show the skipped rollout as not matched.

The context

Give the context one of three ways:

  • Options: --context-kind (user when left out), --context-id, --context-name, and --context-trait name=value for each trait. A trait's value is a string; write name:= followed by JSON for a number, a boolean, an array or an object, as in --context-trait beta:=true or --context-trait age:=30. --context-trait sets a top-level trait; for a nested one, use --context-json.
  • JSON: --context-json '{"identifier": "123", "traits": {"address": {"country": "NZ"}}}', or --context-json @context.json to read the JSON from a file. The object has the fields kind, identifier, name and traits, with kind defaulting to user.
  • A saved context: --saved-context user:123 evaluates a context ConfigDirector has stored from SDK evaluations in that environment, named by its context kind and identifier, with its stored name and traits. It needs the Contexts: Read permission.

Using two of these at once is a mistake in the command, and evaluate exits with 2. With none of them, the config is evaluated for an empty context, as an SDK given no context would, and the first line says for an empty context.

Environment, project and exit codes

--environment takes the environment's slug, shown as Environment slug on the project's Environments tab, and is required: there is no default environment. The project comes from --project, CONFIGDIRECTOR_PROJECT or configdirector.json, as for scan. A renamed config can be evaluated by an old key, and the output then starts with a line naming its current key.

evaluate exits with 0 whenever it evaluated the config, whichever value it got and whichever rule served it. It exits with 2 when it could not, for instance when no config in the project has the key, when no environment has the slug, in which case the message lists the project's environments, or when no saved context in the environment has that context kind and identifier.

evaluate needs a token with Projects: Read, Configs: Read and Environments: Read, and Contexts: Read as well for --saved-context. Nothing is recorded: an evaluation from the CLI is not SDK activity, so it does not keep a config in use or count toward your SDK usage. Each run makes three Admin API requests. With --json, evaluate prints the Admin API's response as it was received, which Evaluating a config describes.

Browse the project

These commands read what a project holds, so you, or a coding agent working in your terminal, can look a config up without opening the dashboard:

CommandWhat it showsPermission
configdirector projects listYour organization's projects, with their slugs and namesProjects: Read
configdirector environments listThe project's environments, with their slugs and names, marking the live onesEnvironments: Read
configdirector configs listThe project's configs, with their type, role, lifetime and lifecycle stateConfigs: Read
configdirector configs get <key>A config's settings, then its targeting rules in every environmentConfigs: Read
configdirector configs activity <key>When SDKs last evaluated the config, per environment, SDK key kind, SDK name and SDK versionConfigs: Read
configdirector segments listThe project's segments, with how many configs use eachSegments: Read
configdirector segments get <key>A segment's condition groups and its environment overridesSegments: Read
configdirector metrics listThe project's metrics, with their kinds, their direction and how many experiments use eachMetrics: Read
configdirector metrics get <event name>A metric's kinds and direction, and each experiment that uses it, with its role and the environments of its runs in progressMetrics: Read
configdirector metrics get --id <metric id>The same for one of several metrics with the same event nameMetrics: Read
configdirector api-token getThe token a command here would use: its organization, name, permissions and expiration, and whether it came from --token, CONFIGDIRECTOR_TOKEN or a sign-in. Never the token itselfAny valid token

projects list lists every project of the token's organization, whichever one is selected, and api-token get reads no project. The other commands take the project from --project, CONFIGDIRECTOR_PROJECT or configdirector.json, as scan does, and also need Projects: Read to find it.

configs get shows the config's settings, then each environment's targeting rules in order, written as evaluate writes them, with the default targeting rule value last:

new-checkout
  Description: Shows the new checkout flow
  Type: boolean
  Role: flag
  Lifetime: temporary
  Availability: client and server SDKs
  Lifecycle state: in-use
  Tags: checkout

test
  Default targeting rule: false

production (live)
  1. plan is one of pro, team: true
  2. 30% get true, 70% get false
  3. in segment Beta testers: true
  Default targeting rule: false

On an experiment, each value comes after the name of its variation, as in 40% get control (Start free trial), 60% get treatment-a (Try it free for 14 days). evaluate names the variation it served the same way, as in treatment-a (Try it free for 14 days), served by rule 2, and configs create names the variation of the default targeting rule value it starts with. Versions before 0.18.0 show the value alone.

A segment condition names the segment when the token has Segments: Read, and shows the segment's ID otherwise. In the same way, segments get names the environment of each environment override by its slug when the token has Environments: Read, and by its ID otherwise. A renamed config can be read by an old key, and the output then starts with a line naming its current key.

configs list takes options that narrow the list:

  • --tag <name> lists the configs that have that tag. Repeat it to list the configs that have any of the tags. It needs Tags: Read to look the names up, and a name no tag has stops the command with exit code 2.
  • --untagged lists the configs that have no tags. It cannot be combined with --tag.
  • --state <state> lists the configs in one lifecycle state: new, in-use, settled, archive-ready or stale.

configs activity prints a header row, then one line per environment, SDK key kind, SDK name and SDK version, with the time of the most recent evaluation in UTC:

ENVIRONMENT   SDK KEY   SDK               LAST EVALUATED
production    server    js-server 1.4.0   2026-10-17 14:03 UTC
test          client    react 2.1.0       2026-10-16 09:12 UTC

projects list, environments list, configs list, configs activity, segments list and metrics list print a header row that names their columns above their lines, such as KEY TYPE ROLE LIFETIME STATE for configs list, and --no-headers leaves it out. An empty list prints only a sentence, such as No configs found in web-app.

api-token get prints one line each for the organization, with its name and id, the token's name, its permissions as the Admin API spells them, when it expires, or never, and where the token came from:

Organization: Acme (9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d)
Name: Laptop
Permissions: configs:read, projects:read
Expires: 2027-01-31 09:30 UTC
Source: the CLI sign-in for Acme

With --json, each of these commands prints the Admin API's response as it was received, except configs list --state, which prints only the configs in that state, and metrics get, which prints the metric as the Admin API listed it for its event name, or returned it for its ID. A key no config or segment has, or an event name or ID no metric has, exits with 2. When several metrics have the event name you give metrics get, it lists them with their IDs and exits with 2, and metrics get --id <metric id> shows one of them, as Metrics describes. projects list and api-token get make one Admin API request and the others make two, plus one per --tag name, one for configs get when a rule uses a segment, one for segments get when the segment has an environment override, and one for metrics get when an experiment that uses the metric has a run in progress.

Create a config

configdirector configs create --key new-checkout --type boolean --role flag --default-value false

configs create creates a config in the project from options that match the Admin API's fields one to one. It never guesses a type or a role and never asks for a missing option, so you, a script or a coding agent always say exactly what to create:

Created new-checkout in web-app: boolean, flag, temporary, client and server SDKs.
Default targeting rule in every environment: false
OptionMeaning
--key <key>Required. The config's key.
--type <type>Required. boolean, string, integer, float, timespan, enum, url or json.
--role <role>Required. config, flag, kill-switch or experiment. Flags and kill switches are booleans, as Roles describes.
--lifetime <lifetime>Required for the config role. temporary or permanent. The other roles decide their own lifetime, as described below.
--default-value <value>Required. The default targeting rule value every environment starts with. It is not the in-code default value your application passes to the SDK.
--description <text>A description shown with the config in the dashboard.
--client-only, --server-onlyServe the config to one kind of SDK only. Without either, client and server SDKs both receive it.
--tag <name>A tag the project already has, by its name. Repeat it for each tag. A name no tag has stops the command with exit code 2.
--new-tag <name>A tag to create in the project's tag catalog and assign, by its name. Repeat it for each tag. A name a tag already has stops the command with exit code 2.
--variation <name=value>A variation of an experiment. Repeat it for each variation.
--hypothesis <text>What an experiment is expected to do, such as Urgency copy raises checkout completion by 5%. Each run keeps the hypothesis it started with. Only an experiment takes one.

The values of --default-value and --variation are read in the config's type: true or false for a boolean, a number for an integer, float or timespan, the text as written for a string, enum or URL, and JSON for a JSON config, where @values.json reads the JSON from a file. A value that does not fit the type stops the command with exit code 2 before anything is sent.

The role decides the lifetime of a feature flag, a kill switch or an experiment, so you can leave --lifetime out for them: a feature flag and an experiment are always temporary, and a kill switch is always permanent. A lifetime the role does not have, such as --role kill-switch --lifetime temporary, stops the command with exit code 2 before anything is sent, and so does --role config without --lifetime. Versions before 0.16.0 need --lifetime for every role.

A config can have up to 20 tags, from --tag and --new-tag together. Every --tag name is looked up before any tag is created, so a misspelled --tag creates nothing, and --tag never creates a tag. A --new-tag name given twice, or a name given with both options, stops the command with exit code 2 before anything is sent, and case doesn't matter in tag names. When a step after creating tags fails, for example because the key is taken, the tags stay in the project's tag catalog, and the command names them so you can pass them with --tag next time:

Created the tag "Payments". It stays in web-app's tag catalog, so pass it with --tag next time.

Constraints have options of their own, and each one belongs to the types listed with it:

TypeOptions
integer, float--min and --max set bounds a value may equal; --exclusive-min and --exclusive-max set bounds a value must stay inside.
timespan--unit (milliseconds, seconds or minutes), --min and --max, which a timespan needs, and --allow-fractions to accept values such as 1.5. A value may equal either bound.
enum--allowed-value for each value the config can take, and --enum-value-type number when the values are numbers. They are strings otherwise.
url--https-only to accept only HTTPS URLs. Without it, any HTTP or HTTPS URL is accepted.
json--json-schema <file>, a file holding the JSON Schema every value must match.

An option given with another type, such as --unit with --type integer, stops the command with exit code 2 and names the types it belongs to. A timespan without --unit, --min or --max stops it with exit code 2 too. configdirector configs create --help lists the options grouped by type.

A timespan read only by server SDKs, from 1 to 120 seconds and starting at 30 in every environment:

configdirector configs create --key checkout-timeout --type timespan --role config --lifetime permanent \
  --unit seconds --min 1 --max 120 --default-value 30 --server-only

configs create exits with 0 when it created the config. When the project already has a config with that key, as its current key or an old one, it creates nothing, prints that config and exits with 1:

web-app already has a config with the key new-checkout, so no config was created:
new-checkout   boolean   flag   temporary   in-use

It exits with 2 when ConfigDirector refuses the config, with the reasons it gave, such as a type the role does not allow or a default targeting rule value outside the bounds. With --json, it prints the created config as the Admin API returned it, or, when the key is taken, the existing config as configs get --json prints it.

configs create needs Projects: Read, Configs: Create, and Configs: Read to show the config that already has the key. --tag also needs Tags: Read to look the names up, and --new-tag needs Tags: Create to create the tags. Each run makes two Admin API requests, plus one per --tag name, one per --new-tag name, and one more when ConfigDirector refuses the key, to look for the config that has it. The config shows in the audit log with the source CLI, as every change made with the CLI does.

Copy a config

configdirector configs copy search-ranking --key search-ranking --to mobile-app --environment qa=staging

configs copy creates a new config from an existing one, under the key --key gives, in the same project or, with --to, in another project of the organization. It never asks for anything, and prints the plan it followed:

Copied search-ranking in web-app to search-ranking in mobile-app.
Environments:
  production (live)   from production   2 rules copied   rule 3 dropped: mobile-app has no segment beta-testers
  qa                  from staging      1 rule copied
Skipped source environments:
  test   mobile-app has no environment with this slug; create it there to copy its rules
Tags:
  search   matched
  growth   created
OptionMeaning
<key>Required. The key of the config to copy, in the linked project. An old key of the config works too.
--key <key>Required. The copy's key, which no config in the destination project may have.
--to <project slug>The project to copy the config into, another project of the organization. Without it, the copy is created in the config's own project.
--environment <destination slug>=<source slug>The environment of the config's project that an environment of the destination project copies its targeting rules from. Repeat it for each one.
--dry-runPrint the plan without creating anything.

The copy gets the config's role, lifetime, type, constraints, variations, SDK availability, description, hypothesis and tags, and every environment's targeting rules and default targeting rule value. It starts as a new config, with no old keys, evaluations or code references, and shares nothing with the config it came from. An archived config cannot be copied; restore it first.

In another project, environments are matched by slug. A destination environment with no environment of the same slug in the config's project needs --environment to name the one it copies from, and the command stops with exit code 2, naming each such environment, until every one has a source; --environment can also replace a slug match. An environment of the config's project with no environment of its slug in the other project is skipped, and the plan says so. Tags are matched by name: a tag the other project doesn't have is created when the token has Tags: Create, and skipped otherwise. Segments are matched by key: a targeting rule that uses a segment the other project doesn't have is dropped, and the plan names it by its position and the segment's key. Create the segment in the other project first to keep the rule. Within one project, everything carries over as it is.

Run it with --dry-run first to see the plan without creating anything. The plan then says what would be copied, dropped, skipped and created:

Nothing was created: this is the plan for copying search-ranking in web-app to search-ranking in mobile-app.
Environments:
  production (live)   from production   2 rules would be copied   rule 3 would be dropped: mobile-app has no segment beta-testers
  qa                  from staging      1 rule would be copied
Source environments that would be skipped:
  test   mobile-app has no environment with this slug; create it there to copy its rules
Tags:
  search   matched
  growth   would be created

configs copy exits with 0 when it copied the config or printed the plan of a dry run, even when the plan drops a rule. It exits with 2 when ConfigDirector refuses the copy, with the reasons it gave, for example a key already in use or an environment with nothing to copy from, and when no config has the key or no project has the --to slug. With --json, it prints the Admin API's response as it was received: the plan, and, unless --dry-run was given, the created config with its targeting rules.

configs copy needs Projects: Read and Configs: Create, and Tags: Create to create the tags another project doesn't have. It makes two Admin API requests. The copy shows in the audit log with the source CLI, noting the config it was copied from.

Targeting rules

configdirector targeting-rules set new-checkout --environment production --rules rules.json

targeting-rules set replaces a config's targeting rules in one environment with the rules in a JSON file. It shows no diff and asks for no confirmation, and it treats a live environment like any other, so look over the file before you run it.

The file holds the default targeting rule value and the rules, in the format the Admin API takes. This one serves true to contexts on the pro or team plan, and false to everyone else:

{
  "defaultValue": false,
  "rules": [
    {
      "type": "conditional",
      "order": 0,
      "conditions": [
        {
          "kind": "attribute",
          "attribute": "traits",
          "trait": "/plan",
          "operator": "is one of",
          "targetType": "text",
          "targetValues": ["pro", "team"]
        }
      ],
      "target": "value",
      "value": true
    }
  ]
}
Replaced the targeting rules of new-checkout in production with 1 rule and the default targeting rule value false.
  • Every rule of the environment is replaced. The file holds all the rules the environment keeps, in the order they are evaluated, and a rule left out of the file is removed. The config's other environments are not touched.
  • IDs. Every rule, condition and percentage in ConfigDirector has an id. Leave it out of a new one, and the CLI gives it a new ID before sending the file. An id in the file is sent as written, so the rules you keep keep their IDs.
  • Start from the current rules. configs get --json prints each environment's rules as an entry of targets, in the shape the file takes. Save the environment's entry, edit it, and pass it to --rules; its other fields, such as environment, are ignored:
    configdirector configs get new-checkout --json \
      | jq '.targets[] | select(.environment.slug == "production")' > rules.json
    # edit rules.json, then:
    configdirector targeting-rules set new-checkout --environment production --rules rules.json
    

    --rules - reads the file from stdin instead, for a script that builds the rules.
  • ConfigDirector checks the rules. The CLI only checks that the file holds a JSON object. ConfigDirector checks the rules against the config's type and constraints, as the dashboard does, and when it refuses them the command exits with 2 and lists its reasons.

configdirector targeting-rules reference prints the format the rules take: notes on how they are evaluated, then the condition kinds, the attributes a condition can test, and the operators of context kind conditions, segment conditions and each target type. With --json, it prints the whole reference document as received, including the JSON Schema of the request targeting-rules set sends, which is the file with environmentId added. The notes are the ones the MCP server gives, so they name its tools: update_targeting_rules does what targeting-rules set does, and get_config what configs get does.

targeting-rules set exits with 0 when it replaced the rules, and with 2 when it could not: no config in the project has the key, no environment has the slug, in which case the message lists the project's environments, or ConfigDirector refused the rules. --environment takes the environment's slug, as for evaluate, and a renamed config can be changed by an old key. With --json, it prints the request it sent, with the IDs it gave, since the Admin API answers with no body.

targeting-rules set needs Projects: Read, Environments: Read and Configs: Update targeting rules, and makes three Admin API requests. targeting-rules reference needs a valid token, whatever its permissions, and no project, and makes one request. The change shows in the audit log with the source CLI.

Experiment runs

configdirector configs runs checkout-cta-copy --environment production
configdirector configs ship checkout-cta-copy --environment production --variation treatment-a
configdirector configs stop checkout-cta-copy --environment production

A run is a period during which an experiment's targeting rules in one environment split traffic between its variations. Saving a percentage rollout starts one, and removing the last rollout ends it. Only experiments have runs.

configs runs lists the experiment's runs in an environment, newest first. For each rollout, it shows how many distinct contexts each variation reached, called exposures, next to the share configured when the run started, and whether the split matches those shares. When the experiment measures metrics, each rollout also shows their results:

Runs of checkout-cta-copy in production (live), newest first:

Running since 2026-11-03 12:00 UTC
  Hypothesis: Urgency copy raises checkout completion by 5%
  Rollout: everyone not caught by a rule above
    control (Start free trial)              412 exposures   configured 50%
    treatment-a (Try it free for 14 days)   398 exposures   configured 50%
    810 contexts exposed, 3201 evaluations. The split matches the configured shares.
    Primary metric: checkout_completed, conversion, higher is better
      control (Start free trial)              2.9%   control
      treatment-a (Try it free for 14 days)   3.5%   +19% (-43% to +154%)   69% chance to beat control   no clear difference
    How long to run, at the pace since 2026-11-04 00:00 UTC: about 98 new exposures a day
      For a real lift of +2%    810 of about 2,082,762 exposures   more than a year remaining
      For a real lift of +5%    810 of about 338,034 exposures     more than a year remaining
      For a real lift of +10%   810 of about 86,501 exposures      more than a year remaining
      For a real lift of +20%   810 of about 22,617 exposures      about 222 days remaining
      For a real lift of +50%   810 of about 4,089 exposures       about 34 days remaining
    A row's lift is one a variation might really have over the control, not the lift measured so far: the smaller it is, the longer the run.
    Whatever the estimate says, a run should cover at least one full week, so every day of the week is in the result.
    Guardrail: support_ticket_opened, count per context, lower is better
      control (Start free trial)              0.12   control
      treatment-a (Try it free for 14 days)   0.13   +8% (-10% to +29%)   22% chance to beat control   no clear difference
  Events with no metric: add_to_cart (340 contexts)
  Results can be up to 25 minutes behind.

Stopped, 2026-10-01 09:00 UTC to 2026-10-15 09:30 UTC
  Hypothesis: Shorter copy raises checkout completion
  Ended with note: No clear difference after two weeks
  Rollout: IF context's trait /plan is one of [pro, team]
    control (Start free trial)              1200 exposures   configured 90%
    treatment-a (Try it free for 14 days)   130 exposures    configured 10%
    1330 contexts exposed, 5120 evaluations. The split matches the configured shares.
    Primary metric: checkout_completed, conversion, higher is better
      control (Start free trial)              3.1%   control
      treatment-a (Try it free for 14 days)   3.8%   +23% (-38% to +96%)   72% chance to beat control   no clear difference
    Guardrail: support_ticket_opened, count per context, lower is better
      control (Start free trial)              0.11   control
      treatment-a (Try it free for 14 days)   0.10   -9% (-41% to +38%)   65% chance to beat control   no clear difference
  Final results, as of 2026-10-15 09:30 UTC, when the run ended.

Each kind a metric reports gets a line with the metric's role (primary metric, secondary metric or guardrail), its name, the kind and its direction, then one row per variation, the control first. Every row shows the variation's value: the share of its exposed contexts that sent the event for conversion, and an average per exposed context for count per context and value per context. Every other variation also shows its lift against the control with the range it is likely in, its chance to beat control, and the verdict: likely better, likely worse or no clear difference, in the metric's direction. With three or more variations, each row also shows the variation's chance to be best. Until every variation has enough exposures, the rollout says the run needs more exposures and shows the values alone. A context exposed to more than one variation is left out of every metric, and the rollout says how many were. How results are computed explains every number. A verdict is a reading of the data so far: what to ship is your call.

While a run is going, its results can be up to 25 minutes behind. Once a run has ended and its final results are in, the last line says so instead. The run's hypothesis, which the run copied from the experiment when it started, and the note it ended with show under its first line. Events with no metric lists the events your application sent with track during the run that no metric measures, with how many contexts sent each. Versions before 0.21.0 show the exposures alone.

A run counts a metric with a filter or a value field only from the moment the metric is attached to the experiment. When that was while the run was going, a line under each of the metric's kinds says since when, and that the events reported before then are not in its numbers. When the metric was not attached while the run was open, the run shows the metric's line, says it did not count it, and shows no numbers:

    Secondary metric: checkout_completed · /plan is one of [team], conversion, higher is better
      Counted since 2026-11-05 09:30 UTC, when this metric was attached to the experiment. Events reported before then are not in these numbers.
      control (Start free trial)              2.1%   control
      treatment-a (Try it free for 14 days)   3.0%   +43% (-5% to +110%)   91% chance to beat control   no clear difference
    Guardrail: checkout_completed · value from /refunded, lower is better
      This run did not count this metric: a metric with a filter or a value field is counted from the moment it is attached to an experiment, and this one was not attached while the run was open.

Versions before 0.23.0 show such a metric by its event name alone, without the line about since when it was counted, and leave out a metric the run did not count.

While a run is going, How long to run follows each rollout's primary metric results once its variations can be compared. For a real lift of 2%, 5%, 10%, 20% and 50% on the primary metric, in its better direction, so -2% to -50% when lower is better, it gives the rollout's exposures so far against those it needs before a variation with that lift has a good chance of reading likely better, and about how many days remain at the pace of new exposures since the time it names. A row's lift is one a variation might really have, not the lift measured so far: the smaller it is, the longer the run. A lift the rollout already has enough exposures for says so, and more than 365 days reads as more than a year. When no new contexts were exposed since that time, the line says the days cannot be estimated, and the rows give the exposures alone. A lift that would take a conversion past 100% gets no row, and the estimate doesn't show while the control's numbers give nothing to estimate from, as when none of its contexts has sent the event yet. New contexts usually arrive more slowly as a run goes on, so take the days as the least the run needs, and run for at least one full week whatever they say. How long a run needs says what the estimate assumes. Versions before 0.22.0 don't show it.

Exposures are counted every so often, so the latest evaluations may not be included yet. A run also says how many evaluations it left out of the exposures: those of anonymous contexts, which have no identifier or are marked anonymous, and those from SDK versions that do not report exposures yet.

configs ship serves one variation to everyone in the environment and ends the run. --variation takes the variation's name or its ID, as configs get --json lists them. In one save of the targeting rules, the default targeting rule value becomes the variation's value and every percentage rollout is removed, including one a conditional rule serves. A conditional rule that serves a single value stays, so the contexts it matches keep getting that value. With no rollout saved, configs ship only changes the default targeting rule value. Experiments walks through a whole A/B test, up to removing the config once it has settled.

configs stop ends the run without choosing a variation. Every percentage rollout is removed, including one a conditional rule serves, and the default targeting rule value stays, so the contexts that were in a rollout get that value. A conditional rule that serves a single value stays here too.

Both print the rules they saved:

Shipped treatment-a (Try it free for 14 days) in production (live).

production (live)
  1. plan is one of pro, team: control (Start free trial)
  Default targeting rule: treatment-a (Try it free for 14 days)

Both take --note <text>, up to 1,000 characters on why the variation is shipped or the run is stopped. The ended run keeps it, and configs runs and the dashboard show it with the outcome.

Neither asks for confirmation, and both treat a live environment like any other, so check the environment before you run them. The change takes effect right away.

configs runs says so when the config has no runs in the environment, and exits with 0. configs ship exits with 2 when --variation matches none of the experiment's variations, or several with the same name, and lists them with their IDs, and when the config has no variations, since only an experiment has them. configs stop exits with 2 when the config is not an experiment or the environment holds no percentage rollout, since there is no run to stop. All three exit with 2 when no config has the key or no environment has the slug, and the message then lists the project's environments. You can name a renamed experiment by an old key. With --json, they print the Admin API's response as it was received: the runs, or the config with its targeting rules in every environment.

configs runs needs Projects: Read, Environments: Read and Configs: Read, and makes four Admin API requests. configs ship needs those and Configs: Update targeting rules, and also makes four requests. configs stop needs Projects: Read, Environments: Read and Configs: Update targeting rules, and makes three. configs ship and configs stop make one more when a rule uses a segment. A shipped or stopped run shows in the audit log with the source CLI.

Segments

configdirector segments create --segment beta-testers.json
configdirector segments update beta-testers --segment beta-testers.json
configdirector segments delete beta-testers

segments create and segments update write a segment from a JSON file, and segments delete deletes one. They show no diff and ask for no confirmation, so look over the file before you run them.

The file holds the segment's key, its name and its condition groups, in the format the Admin API takes. A context is in the segment when every condition of any one group matches. overrides is optional, and maps an environment's ID to the condition groups that environment uses instead, as Environment overrides describes. This segment holds the contexts whose email ends in @example.com, and those on the beta plan in New Zealand or Australia, except in the environment with the ID 7e6d5c4b-3a29-4810-8f7e-6d5c4b3a2918, where it holds only staff:

{
  "key": "beta-testers",
  "name": "Beta testers",
  "groups": [
    [
      {
        "kind": "attribute",
        "attribute": "traits",
        "trait": "/email",
        "operator": "ends with any of",
        "targetType": "text",
        "targetValues": ["@example.com"]
      }
    ],
    [
      {
        "kind": "attribute",
        "attribute": "traits",
        "trait": "/plan",
        "operator": "is one of",
        "targetType": "text",
        "targetValues": ["beta"]
      },
      {
        "kind": "attribute",
        "attribute": "traits",
        "trait": "/country",
        "operator": "is one of",
        "targetType": "text",
        "targetValues": ["NZ", "AU"]
      }
    ]
  ],
  "overrides": {
    "7e6d5c4b-3a29-4810-8f7e-6d5c4b3a2918": [
      [
        {
          "kind": "attribute",
          "attribute": "traits",
          "trait": "/email",
          "operator": "ends with any of",
          "targetType": "text",
          "targetValues": ["@staff.example.com"]
        }
      ]
    ]
  }
}

segments create --segment beta-testers.json prints what it created, the way segments get shows a segment:

Created segment beta-testers in web-app.
beta-testers
  Name: Beta testers

Project definition
  1. email ends with any of @example.com
  2. plan is one of beta and country is one of NZ, AU

Override in production
  1. email ends with any of @staff.example.com
  • IDs. Every condition in ConfigDirector has an id. Leave it out of a new one, in the condition groups or in an override, and the CLI gives it a new ID before sending the file. An id in the file is sent as written, so the conditions you keep keep their IDs.
  • Start from the current segment. segments get --json prints a segment in the shape the file takes. Save it, edit it, and pass it to --segment; its other fields, such as usages, are ignored:
    configdirector segments get beta-testers --json > beta-testers.json
    # edit beta-testers.json, then:
    configdirector segments update beta-testers --segment beta-testers.json
    

    --segment - reads the file from stdin instead, for a script that builds the segment.
  • Environment IDs. overrides is keyed by the environment's ID, not its slug. environments list --json prints the ID of each environment.
  • What update replaces. segments update <key> replaces the key, the name and the condition groups of the segment the key names, so a different key in the file renames it. The segment keeps its own ID whatever id the file holds, so a file saved from another segment updates the one you name. Without overrides in the file, the environment overrides stay as they are. With "overrides": {}, they are all removed, and with a map, exactly those environments are overridden and the others go back to the project definition.
  • ConfigDirector checks the segment. The CLI only checks that the file holds a JSON object. ConfigDirector checks the rest, as the dashboard does, and when it refuses the segment, for example because another segment has its key, the command exits with 2 and lists its reasons.

segments delete <key> deletes the segment and its environment overrides:

Deleted segment beta-testers from web-app.

It is refused while the targeting rules of any config use the segment, in any environment; archived configs are not counted. The command then exits with 2 and lists those configs with the environments whose rules use the segment, so you can remove those segment conditions with targeting-rules set first:

Error: The targeting rules of 2 configs use the segment beta-testers, so it was not deleted:
  new-checkout in production
  dark-mode in test, production
Remove those segment conditions first, with configdirector targeting-rules set.

The three commands exit with 0 when they wrote or deleted the segment, and with 2 when they could not: no segment in the project has the key given to update or delete, ConfigDirector refused the segment, or a config uses the segment you tried to delete. With --json, create and update print the segment as the Admin API returned it, and delete prints { "deletedSegmentKey": "beta-testers" }, with the key as you gave it, since the Admin API answers with no body.

segments create needs Projects: Read and Segments: Create, segments update needs Projects: Read, Segments: Read and Segments: Update, and segments delete needs Projects: Read and Segments: Delete. With Environments: Read, the output names environments by their slug, and without it, by their ID. create makes two Admin API requests and update three, plus one to name the environments when the segment has an override; delete makes two, plus one to name the environments when it is refused. The change shows in the audit log with the source CLI.

Metrics

configdirector metrics create --event-name checkout_completed --kind conversion --kind value-per-context --direction higher-is-better
configdirector metrics create --event-name checkout_completed --filter team-plan.json --value-field /items --kind value-per-context --direction higher-is-better
configdirector metrics update checkout_completed --direction lower-is-better
configdirector metrics delete --id 4f5a6b7c-8d9e-4f0a-9b1c-3d4e5f6a7b8c

A metric is what an experiment measures: the events with one name your application sends with the SDK's track call, all of them or only those whose details match the metric's filter, the numbers it reports, and whether a higher or a lower number is better. A project can have several metrics on one event name, told apart by their filter and value field. The commands show a metric by its event name, then its filter's conditions, then its value field, as in checkout_completed · /plan is one of [team] · value from /items, and take its event name, exactly as your application sends it, while only one metric has it. configs runs shows the results of the metrics an experiment measures, as Experiment runs describes. You attach metrics to an experiment, and choose its primary metric, on the experiment's Settings tab in the dashboard, or through the Admin API or the MCP server; the CLI has no command for it.

metrics create creates a metric for an event name:

OptionMeaning
--event-name <event name>Required. The event name, exactly as your application passes it to track, 1 to 150 characters.
--kind <kind>Required. A number the metric reports. Repeat it for each: conversion, the share of exposed contexts that sent the event at least once; count-per-context, how many times each exposed context sent it, on average; value-per-context, the value your application sent with the event per exposed context, on average. A context that sent nothing counts as zero.
--direction <direction>Required. higher-is-better, as for purchases, or lower-is-better, as for support tickets or errors. Every verdict on the metric follows it.
--filter <file>A JSON file holding the conditions an event's details must match for the event to count, or - to read them from stdin. Without it, every event with the name counts.
--value-field <pointer>A JSON pointer, such as /items, to the field of the event's details holding the number that value per context sums in place of the event's value. It needs --kind value-per-context. An event without a number there still counts as an event and adds nothing to the sum.
--description <text>What the event means.

The --filter file holds 1 to 5 conditions, all of which an event must match, in the shape metrics get --json prints a metric's filter in. For the checkouts on the Team plan:

[{ "field": "/plan", "targetType": "text", "operator": "is one of", "targetValues": ["team"] }]

field is a JSON pointer into the details your application sends with the event. A text condition takes is one of or is NOT one of, with up to 20 target values; a number condition takes =, !=, >, >=, < or <=, with one number written as text, such as "2"; and a boolean condition takes equals, with "true" or "false". A condition means what it means in a targeting rule, so a field an event lacks reads as empty text, and is NOT one of and != count an event without it. The Admin API describes the conditions in full.

A metric keeps its filter and value field for its whole life: for others, create another metric. A run counts a metric with a filter or a value field only from the moment the metric is attached to the experiment, as Experiment runs shows. ConfigDirector refuses a metric with the same event name, filter and value field as another of the project.

It prints the metric it created, the way metrics get shows one:

Created metric checkout_completed in web-app.
checkout_completed
  Kinds: conversion, value per context
  Direction: higher is better

No experiment uses it.

Once experiments use a metric, metrics get lists them with the metric's role in each, the kind a primary metric decides on, and the environments where a run is in progress:

checkout_completed
  Description: Orders paid for.
  Kinds: conversion, value per context
  Direction: higher is better

Used by
  checkout-cta-copy: primary metric on conversion, running in production
  pricing-page-copy: guardrail

metrics update <event name> changes what its options name and leaves the rest as it is: --kind, repeated, replaces the kinds, --direction the direction, and --description the description, which --description "" removes. A metric keeps its event name, filter and value field; for others, create another metric. Removing a kind an experiment's primary metric decides on is refused, and the command lists those experiments:

Error: 1 experiment decides on a kind this change removes, so checkout_completed was not updated:
  checkout-cta-copy decides on value per context
Give it another primary kind first, on the experiment's Settings tab in the dashboard.

metrics delete <event name> deletes the metric and detaches it from the experiments that use it. Events with its name keep being counted, so a metric created again for the name without a filter or a value field, and attached again, shows their history, while one with a filter or a value field is counted from the moment it is attached. The deletion is refused while an experiment that uses the metric has a run in progress, and the command lists those experiments with the environments of their runs:

Error: 1 experiment with a run in progress uses checkout_completed, so it was not deleted:
  checkout-cta-copy, running in production
Ship or stop each run first, with configdirector configs ship or configs stop, or detach the metric on the experiment's Settings tab in the dashboard.

metrics get, metrics update and metrics delete take the event name while only one metric has it. When several metrics have it, they change nothing: they list the metrics with their IDs and exit with 2, and --id <metric id>, in place of the event name, names one of them:

Error: 2 metrics in web-app have the event name "checkout_completed". Name one with --id:
  1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f   checkout_completed
  4f5a6b7c-8d9e-4f0a-9b1c-3d4e5f6a7b8c   checkout_completed · /plan is one of [team]
Version 0.23.0 is the first that handles several metrics on one event name. Earlier versions act on the first metric ConfigDirector lists for the event name, so their metrics update and metrics delete can change or delete another metric than the one you mean. Upgrade every CLI that changes your metrics, CI included, before you create a second metric on an event name.

None of the three asks for confirmation. They exit with 0 when they wrote or deleted the metric, and with 2 when they could not: no metric in the project has the event name or ID given to update or delete, several have the event name, ConfigDirector refused the metric, for example because the project already has one with the same event name, filter and value field, or an experiment's primary metric or run in progress stopped the change. With --json, create and update print the metric as the Admin API returned it, and delete prints { "deletedMetricId": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "deletedEventName": "checkout_completed" }, since the Admin API answers with no body.

metrics create needs Projects: Read and Metrics: Create, metrics update needs Projects: Read, Metrics: Read and Metrics: Update, and metrics delete needs Projects: Read, Metrics: Read and Metrics: Delete. With Environments: Read, update and delete name environments by their slug, and without it, by their ID. create makes two Admin API requests, and update and delete three, plus one to name the environments when a run is in progress. The change shows in the audit log with the source CLI.

Archive a config

configdirector configs archive new-checkout

configs archive archives a config: it is removed from the project and from what SDKs receive, so your applications get their in-code default value for it. You can restore it from the dashboard for 30 days, with its targeting rules intact, and after that it is deleted for good, as Archiving describes:

Archived new-checkout in web-app. It can be restored from the dashboard for 30 days.

It asks for no confirmation and does not check whether your code still reads the key. Run scan first and look at every reference to the key, the indirect ones included, since an application that still reads it after the archive gets its in-code default value and raises a Config not found alert. A renamed config can be archived by an old key.

configs archive exits with 0 when it archived the config, and with 2 when no config in the project has the key, which includes a config already archived. With --json, it prints { "archivedConfigKey": "new-checkout" }, with the key as you gave it, since the Admin API answers with no body.

configs archive needs Projects: Read and Configs: Archive (configs:archive), and makes two Admin API requests. The change shows in the audit log with the source CLI.

Output

Every command prints text for people by default. With --json, it prints JSON instead, for scripts and CI. Errors and the token prompt go to stderr, so with --json the JSON is all that reaches stdout:

configdirector scan --json | jq -r '.references[] | select(.key == "new-checkout") | "\(.file):\(.line)"'

validate --json prints the scan's JSON with a findings array, and still exits with 1 when the array is not empty. Shortened to one reference of each kind and one finding:

{
  "project": "web-app",
  "filesScanned": 4,
  "references": [
    {
      "key": "new-checkout",
      "file": "src/checkout.ts",
      "line": 5,
      "kind": "direct",
      "sdk": "js-server",
      "call": "getValue",
      "argument": "NEW_CHECKOUT",
      "default": { "type": "boolean", "value": false },
      "test": false
    },
    {
      "key": "new-checkout",
      "file": "src/flags.ts",
      "line": 1,
      "kind": "indirect",
      "test": false
    }
  ],
  "dynamicReferences": [
    {
      "file": "src/theme.tsx",
      "line": 5,
      "sdk": "react",
      "call": "useConfigValue",
      "argument": "setting.key"
    }
  ],
  "findings": [
    {
      "kind": "availability-mismatch",
      "key": "fraud-threshold",
      "file": "src/theme.tsx",
      "line": 4,
      "sdk": "react",
      "sdkType": "client",
      "configAvailableTo": ["server"]
    }
  ]
}

A direct reference has argument when its key came from a constant, default when the call passes an in-code default value, and getterType when the getter's name sets the type. In scan --json, each direct and indirect reference also has its snippet, which validate --json leaves out:

"snippet": {
  "firstLine": 3,
  "lines": [
    "const client = createClient(\"YOUR-SERVER-SDK-KEY\");",
    "",
    "export const isNewCheckout = () => client.getValue(NEW_CHECKOUT, false);",
    "",
    "export const checkoutPath = () => (isNewCheckout() ? \"/checkout/v2\" : \"/checkout\");"
  ],
  "language": "typescript",
  "truncatedLines": []
}

firstLine is the number of the snippet's first line in the file, language the language to highlight the lines as, and truncatedLines the numbers of the lines cut to 250 characters. Each finding has a kind, the key, the file and the line, and the config facts it was checked against:

kindAlso has
unknown-key
deprecated-keycurrentKey
type-mismatchconfigType, servedAs, and default, getterType or both
availability-mismatchsdk, sdkType, configAvailableTo
enum-value-not-alloweddefault, allowedValues

The JSON Schema in the package describes every field.