vercel flags

The vercel flags command manages Vercel Flags for a project from the command line. Use vercel flags to create and update feature flags, view version history and evaluation metrics, manage rules and rollouts, define entities and attribute labels, or configure reusable segments and SDK keys.

vercel flags list

vercel flags create [slug]

vercel flags inspect [flag]

vercel flags versions [flag]

vercel flags versions diff [flag] --revision [number]

vercel flags evaluations [flag]

vercel flags open [flag]

vercel flags update [flag]

vercel flags set [flag]

vercel flags split [flag]

vercel flags rollout [flag]

vercel flags rules ls [flag]

vercel flags enable [flag]

vercel flags disable [flag]

vercel flags archive [flag]

vercel flags unarchive [flag]

vercel flags rm [flag]

vercel flags segments ls

vercel flags entities ls

vercel flags labels ls [entity.attribute]

Boolean flags are created by default. The vercel flags create command creates a new feature flag.

vercel flags create welcome-message --kind string --description "Homepage welcome copy" \
  --variant control="Welcome back" --variant treatment="Start for free"

For string, number, and JSON flags, repeat --variant VALUE[=LABEL] to define the exact variants you want to create. If you omit --variant in a terminal, the CLI prompts you to add variants interactively. In non-interactive environments, you must pass --variant.

For JSON flags, use repeated --variant '<JSON>' or --variant '<JSON>'=Label values:

vercel flags create layout-config --kind json \
  --variant '{"theme":"light","sidebar":false}'=Light \
  --variant '{"theme":"dark","sidebar":true}'=Dark

JSON variants accept any valid JSON value, including objects, arrays, booleans, numbers, strings, and null.

vercel flags create search-config --kind json \
  --variant '{"mode":"fast","limit":10}' \
  --variant '{"mode":"accurate","limit":50}'

Boolean flags always use the built-in false and true variants, labelled Off and On.

New boolean flags serve true in development and false in preview and production. The create output shows the initial environment behavior for the flag you just created.

Use vercel flags open to jump straight to the Vercel dashboard.

vercel flags open welcome-message

Use vercel flags versions to list saved revisions for a flag. The default table output includes the revision number, author, change message, timestamp, and changed environments. You can also run vercel flags versions list [flag] for the same list output.

vercel flags versions welcome-message

By default, vercel flags versions uses the linked project. To query another project, pass the project name or ID with --project.

Filter versions by changed environment with --environment or -e:

vercel flags versions welcome-message --environment production

The command returns up to 20 versions per page by default. Use --limit to set a page size from 1 to 100. When another page is available, the CLI prints a next-page command with --next:

vercel flags versions welcome-message --limit 10
vercel flags versions welcome-message --limit 10 --next next_page_cursor

The table output stays summary-only. Use --json for scripting and automation when you need the full version snapshot. Each version includes a data object with the flag configuration for that revision:

vercel flags versions welcome-message --json

{
  "versions": [
    {
      "id": "flag_version_3",
      "flagId": "flag_abc123",
      "revision": 3,
      "author": "Ada Lovelace",
      "createdBy": "user_456",
      "message": "Updated production targeting",
      "createdAt": 1783602795208,
      "changedEnvironments": ["production"],
      "data": {
        "description": "My awesome feature flag",
        "variants": [
          { "id": "off", "value": false, "label": "Off" },
          { "id": "on", "value": true, "label": "On" }
        ],
        "environments": {
          "production": {
            "active": true,
            "rules": [
              {
                "id": "rule_pro_users",
                "conditions": [
                  {
                    "lhs": {
                      "type": "entity",
                      "kind": "user",
                      "attribute": "plan"
                    },
                    "cmp": "eq",
                    "rhs": "pro"
                  }
                ],
                "outcome": { "type": "variant", "variantId": "on" }
              }
            ],
            "pausedOutcome": { "type": "variant", "variantId": "off" },
            "fallthrough": { "type": "variant", "variantId": "off" },
            "targets": {
              "user": {
                "id": {
                  "on": [{ "value": "user_123", "note": "Beta customer" }]
                }
              }
            },
            "revision": 3
          }
        },
        "seed": 12345,
        "state": "active"
      }
    }
  ],
  "pagination": {
    "next": null
  }
}

Use vercel flags versions diff to compare a revision with the immediately preceding revision:

vercel flags versions diff welcome-message --revision 4

The diff output is a readable summary of the flag change. It starts with the revision, flag, and project context, then shows the author, message, changed environments, and sections for changed settings and environments. Revision 0 appears in version history as the creation revision, but it can't be diffed because it has no previous revision.

Use --json to output a normalized, structured diff:

vercel flags versions diff welcome-message --revision 4 --json

The diff JSON includes flag, revision, previousRevision, version, previousVersion, and changes. The version and previousVersion fields use the same summary fields as the version list output. Every item in changes includes path and action. The remaining fields depend on the action:

• action: "added" includes only after
• action: "removed" includes only before
• action: "changed" includes both before and after

If revision 0 has no saved message, version history shows Flag created. When a diff has no semantic changes, the command prints No changes detected. If the requested revision is unavailable, the error reports how many revisions are available.

Use vercel flags evaluations [flag] to view evaluation metrics during a time range. Pass a flag slug or ID to query one flag, or omit it to query every flag in the project. By default, the command uses the linked project and groups by variant for one flag or flag for the whole project.

vercel flags evaluations new-checkout --since 1h --granularity 15m

Use --group-by to break evaluations down by other dimensions. You can repeat it to group by several dimensions at once:

vercel flags evaluations new-checkout --group-by sdk-key --group-by client

Without a flag, the command groups evaluations by flag across the whole project:

vercel flags evaluations --group-by sdk-key --since 24h

When you run the command outside the linked project directory, use the global --cwd option to select it:

vercel flags evaluations new-checkout --cwd /path/to/project

By default, vercel flags evaluations shows the aligned UTC time range, bucket interval, and project. It also shows totals, statistics, and sparklines for each group. When grouping one flag by variant, the CLI displays current variants with their configured values and labels. It labels evaluations without a variant as Default in Code and displays deleted or unknown variant IDs unchanged. SDK keys show their label, or their hash when the key is deleted or unknown.

For example, the command above can return:

> Period: 2026-07-10 10:00 to 2026-07-10 11:00 (UTC) [1h]
> Interval: 15m
> Project: my-storefront (acme)

    Variants  total  avg      min          max
  false: Off    180   45  30 at 10:00  60 at 10:45
    true: On    100   25  10 at 10:00  40 at 10:30

    Variants
  false: Off  ▁▆▃█
    true: On  ▁▃█▆

If the selected period has no evaluation data, the command prints No data found for this period. and exits successfully.

Pass --json to output exact bucket data without text formatting. The groupBy array lists the dimensions in use. Each buckets entry includes the timestamp, the evaluation count, and one or more fields for the grouped dimensions. When grouping by variant, variantId is the variant ID or null for Default in Code, and variantValue contains the configured value. When you pass a flag, the variants object maps current variant IDs to their configured values. Without a flag, flag is null and the output has no variants object.

vercel flags evaluations new-checkout --since 1h --granularity 15m --json

{
  "flag": "new-checkout",
  "groupBy": ["variant"],
  "variants": {
    "off": false,
    "on": true
  },
  "groupBy": ["variant"],
  "startTime": "2026-07-10T10:00:00.000Z",
  "endTime": "2026-07-10T11:00:00.000Z",
  "granularity": {
    "minutes": 15
  },
  "truncated": false,
  "buckets": [
    {
      "timestamp": "2026-07-10T10:00:00.000Z",
      "variantId": "off",
      "variantValue": false,
      "evaluations": 30
    },
    {
      "timestamp": "2026-07-10T10:00:00.000Z",
      "variantId": "on",
      "variantValue": true,
      "evaluations": 10
    },
    {
      "timestamp": "2026-07-10T10:15:00.000Z",
      "variantId": "off",
      "variantValue": false,
      "evaluations": 50
    },
    {
      "timestamp": "2026-07-10T10:15:00.000Z",
      "variantId": "on",
      "variantValue": true,
      "evaluations": 20
    },
    {
      "timestamp": "2026-07-10T10:30:00.000Z",
      "variantId": "off",
      "variantValue": false,
      "evaluations": 40
    },
    {
      "timestamp": "2026-07-10T10:30:00.000Z",
      "variantId": "on",
      "variantValue": true,
      "evaluations": 40
    },
    {
      "timestamp": "2026-07-10T10:45:00.000Z",
      "variantId": "off",
      "variantValue": false,
      "evaluations": 60
    },
    {
      "timestamp": "2026-07-10T10:45:00.000Z",
      "variantId": "on",
      "variantValue": true,
      "evaluations": 30
    }
  ]
}

Each dimension adds its own fields to a bucket:

vercel flags evaluations --group-by flag --group-by sdk-key --since 24h --granularity 1d --json

{
  "flag": null,
  "groupBy": ["flag", "sdk-key"],
  "startTime": "2026-07-09T00:00:00.000Z",
  "endTime": "2026-07-11T00:00:00.000Z",
  "granularity": {
    "days": 1
  },
  "truncated": false,
  "buckets": [
    {
      "timestamp": "2026-07-10T00:00:00.000Z",
      "flagKey": "new-checkout",
      "sdkKeyId": "a1b2c3d4e5f6",
      "sdkKeyLabel": "storefront-production",
      "sdkKeyEnvironment": "production",
      "evaluations": 280
    }
  ]
}

vercel flags evaluations rounds the start time down and the end time up to bucket boundaries. The JSON startTime and endTime fields contain the aligned range. The buckets array includes only returned buckets and doesn't add buckets with no data.

When the selected period has no evaluation data, the buckets array is empty.

vercel flags evaluations returns up to the 100 most evaluated groups, such as variants, flags, or SDK keys. Human-readable output warns when additional groups are omitted. In JSON output, truncated is true when the limit omits less frequently evaluated groups.

vercel flags evaluations exits with a non-zero status when validation fails or it can't retrieve the project, flag, or evaluation data. Common validation and project error codes include:

Flag lookup errors use the code returned by the Vercel API. Evaluation data errors can use FORBIDDEN, RATE_LIMITED, TIMEOUT, INTERNAL_ERROR, or BAD_REQUEST.

In human-readable mode, the CLI prints error messages to the terminal. With --json, validation and request errors use the following shape after command-line argument parsing succeeds:

{
  "error": {
    "code": "INVALID_GRANULARITY",
    "message": "Invalid granularity \"10m\". Use one of: 1m, 5m, 15m, 1h, 4h, 1d."
  }
}

Use vercel flags update to change an existing variant's value, label, or both. If you omit one of the update flags, the CLI can guide you interactively.

vercel flags update welcome-message --variant control --value welcome-back \
  --label "Welcome back" --message "Refresh control copy"

--variant matches a variant ID or current value. Run vercel flags inspect if you want to confirm the available variants before updating them.

For JSON flags, --variant can be the variant ID or the current JSON value, and --value must be valid JSON:

vercel flags update layout-config \
  --variant '{"theme":"light","sidebar":false}' \
  --value '{"theme":"light","sidebar":true}' \
  --label "Light+"

JSON variant selection matches the parsed JSON value, not the label. Run vercel flags inspect if you want to copy the current variant ID or value before updating it.

For boolean flags, vercel flags update can rename the true or false variant labels, but it cannot change the boolean values themselves.

Use vercel flags set to choose which variant a specific environment serves.

vercel flags set welcome-message --environment preview --variant control \
  --message "Serve the control copy in preview"

Use vercel flags split to bucket traffic across variants in one environment. The command configures the environment's fallthrough outcome, which applies when no targeting rule matches.

vercel flags split ai-summary-model --environment production --by user.id \
  --default-variant stable --weight stable=95 --weight candidate=5 \
  --message "Route summary traffic to the candidate model"

The --by option selects the entity attribute used for stable bucketing. Define the entity and attribute with vercel flags entities or in the dashboard before running the command. For example, create a user entity with an id attribute, then pass --by user.id. You can't use a timestamp attribute for bucketing.

Pass one --weight value for every variant. Weights are ratios that Vercel Flags normalizes into percentages, so stable=1 and candidate=1 produce the same allocation as stable=50 and candidate=50. Use 0 for variants that should receive no traffic. At least one variant must have a weight greater than 0.

If you omit split options in an interactive terminal, the CLI prompts for the environment, bucketing attribute, weights, fallback variant, and revision message. In non-interactive environments, pass the required options explicitly.

For boolean flags, vercel flags split uses the false variant as the default fallback. For String, Number, and JSON flags, pass --default-variant. The default variant is served when the entity attribute used for bucketing is unavailable.

vercel flags split ai-chat-model -e preview --by user.id \
  --default-variant stable --weight stable=50 --weight candidate=50 \
  --weight legacy=0

If you rerun vercel flags split for an environment that already has a weighted split, you can update only the weights, the fallback variant, or the revision message. If you omit --by, --weight, or --default-variant, the CLI keeps the current split values.

Use vercel flags rollout to move traffic from one variant to another over time.

vercel flags rollout redesigned-checkout --environment production --by user.id \
  --stage 5,6h --stage 10,6h --stage 25,12h --stage 50,1d \
  --message "Start redesigned checkout rollout"

Each --stage defines the percentage of traffic sent to the rollout variant and how long that stage lasts. After the last stage finishes, the environment serves the final percentage of the target variant indefinitely. The final percentage is 100% unless you set --final-percentage.

vercel flags rollout welcome-message --environment production --by user.id \
  --from-variant control --to-variant treatment --default-variant control \
  --stage 10,2h --stage 50,12h --start 2026-04-16T09:00:00Z

For Boolean flags, vercel flags rollout defaults to rolling from false to true and using the false variant as the fallback. For String, Number, and JSON flags, pass --from-variant, --to-variant, and optionally --default-variant. These options accept either a variant ID or a variant value, and using the ID is often easier for JSON variants.

If you rerun vercel flags rollout for an environment that already has a rollout, you can update only the stages and keep the current bucketing attribute, start time, and variants.

Use vercel flags rules to manage targeting rules in a flag environment. Rules evaluate from top to bottom before the environment's fallthrough outcome. The first matching rule determines the outcome Vercel Flags serves.

vercel flags rules ls my-feature --environment production

Add a rule by passing one or more conditions and an outcome:

vercel flags rules add my-feature --environment production \
  --condition user.plan:eq:pro --variant on \
  --message "Enable Pro users"

Rule conditions use these forms:

Repeat --condition to add multiple conditions. You can also separate conditions with semicolons in one value:

vercel flags rules add my-feature --environment production \
  --condition "user.plan:eq:pro;team.tier:eq:enterprise" --variant on

Timestamp attributes accept a date and time instead of a plain value:

vercel flags rules add my-feature --environment production \
  --condition user.signupAt:after:2026-04-16T09:00:00Z --variant on

See available rule operators for the complete operator list, including aliases, timestamp operators, and value formats.

Use the same outcome options as vercel flags set, vercel flags split, and vercel flags rollout when adding or updating a rule. For example, a matching rule can serve one variant, split traffic across variants, or run a progressive rollout:

vercel flags rules add my-feature --environment production \
  --condition user.plan:eq:pro --by user.id \
  --weight off=90 --weight on=10 --position 1

Use the rule ID from vercel flags rules ls to update, move, or remove a rule:

vercel flags rules update my-feature rule_123 --environment production \
  --condition user.plan:eq:enterprise

vercel flags rules move my-feature rule_123 --environment production \
  --position 1

vercel flags rules rm my-feature rule_123 --environment production

When you update, move, or remove a rule in an environment that reuses another environment's configuration, the CLI copies the effective rules into the selected environment and disables configuration reuse for that environment.

Use these operators in vercel flags rules conditions and vercel flags segments rule criteria. Operators can compare entity attributes or segments, depending on the command syntax.

The list operators oneOf, !oneOf, containsAllOf, containsAnyOf, and containsNoneOf accept comma-separated values, such as user.plan:oneOf:pro,enterprise. The existence operators ex and !ex don't require a value, such as user.email:ex.

Attributes with the timestamp type accept only these four operators, the same four the dashboard offers. The CLI rejects every other operator on timestamp attributes, including eq, ex, oneOf, contains, and startsWith.

The CLI also accepts on-or-after and on-or-before as legacy spellings of at-or-after and at-or-before.

Pass the value as an ISO 8601 date and time, such as 2026-04-16T09:00:00Z, or as epoch milliseconds, such as 1776330000000. The date and time must include at least hours and minutes, so the CLI rejects date-only values such as 2026-04-16. A date and time without a timezone uses the timezone of the machine that runs the command. The CLI rejects epoch values in seconds.

Your application must pass timestamp values as epoch milliseconds in the evaluation context, for example Date.now(). See entity attribute types.

Use vercel flags targets to assign a fixed variant to specific entity values in a flag environment. With targeting active, targets evaluate before conditional rules. Define the entity and attribute first.

Saving targets doesn't activate targeting. If the environment serves a static value or reuses another environment, the CLI warns that the saved targets don't affect evaluation. Run vercel flags use-targeting <flag> --environment <environment> to activate targeting while keeping the current fallthrough outcome.

List the direct targets for a flag:

vercel flags targets list my-feature --environment production
vercel flags targets ls my-feature -e production --json

Add one or more targets as entity.attribute=value. Boolean flags default to the true variant. For other flag types, pass --variant with a variant ID or value. A value already assigned to another variant moves to the selected variant.

vercel flags targets add my-feature -e production user.id=user_123 user.id=user_456
vercel flags targets add welcome-message -e preview --variant treatment team.id=team_789

Append |label to set the attribute value's label in the same command. Quote the argument so your shell doesn't treat | as a pipe:

vercel flags targets add my-feature -e production "team.id=team_789|Vercel"

Remove targets with remove or its rm alias:

vercel flags targets remove my-feature -e production user.id=user_123
vercel flags targets rm my-feature -e production user.id=user_456

All three subcommands accept --project, --environment (-e), and --json. add and remove also accept --message for a revision message. Pass the environment explicitly in scripts and when using --json.

The enable and disable commands are shortcuts for boolean flags. They control whether an environment serves the true variant or the false variant. If you do not provide the --environment option, the CLI prompts you to select one interactively.

vercel flags enable my-feature --environment production --message "Resume rollout"

vercel flags disable my-feature -e production --variant false \
  --message "Pause rollout in production"

A flag must be archived before it can be deleted. Archived flags stop evaluating. Use vercel flags unarchive or the dashboard to restore an archived flag with its previous configuration.

vercel flags archive my-feature --yes

vercel flags unarchive my-feature --yes

vercel flags unarchive prints a warning and exits successfully without making changes when the flag is already active.

vercel flags rm my-feature --yes

The vercel flags segments subcommand manages reusable segments for the linked project. A segment can include exact entity values, exclude exact entity values, and define rules based on entity attributes.

vercel flags segments ls

vercel flags segments inspect beta-users --json

Create a segment with exact included values by repeating --add:

vercel flags segments create beta-users --label "Beta users" \
  --add include:user.id=user_123 --add include:user.id=user_456

Create a segment from rules by using the rule: target:

vercel flags segments create enterprise-users --label "Enterprise users" \
  --add rule:user.plan:eq:enterprise

Update a segment by adding or removing criteria:

vercel flags segments update beta-users --add include:user.id=user_789 \
  --remove include:user.id=user_123

vercel flags segments update enterprise-users \
  --add rule:user.email:ends-with:@company.com \
  --remove rule:user.plan:eq:pro

Delete a segment with rm:

vercel flags segments rm beta-users --yes

Segments can't be deleted while they are referenced by flags or other segments. Remove every reference first, then run vercel flags segments rm.

Segment criteria use these forms:

Segment rules use the same operators as conditional flag rules. See available rule operators for the complete operator list, including aliases and value formats.

For list operators such as oneOf, pass comma-separated values:

vercel flags segments create paid-users --label "Paid users" \
  --add rule:user.plan:oneOf:pro,enterprise

For timestamp attributes, use the timestamp operators with an ISO 8601 date and time:

vercel flags segments create early-adopters --label "Early adopters" \
  --add rule:user.signupAt:before:2026-04-16T09:00:00Z

Use --data when you want to provide the full segment data JSON. The JSON object can include rules, include, and exclude fields:

vercel flags segments create staff --label Staff \
  --data '{"rules":[],"include":{"user":{"email":[{"value":"me@company.com"}]}},"exclude":{}}'

The vercel flags entities subcommand manages the entities and attributes that rules, segments, splits, and rollouts can target. Define an entity and its attributes before you reference them in a condition or with --by.

vercel flags entities ls

Create an entity by passing its kind and one or more attributes as KEY:TYPE:

vercel flags entities create user --label User \
  --attribute id:string --attribute plan:string --attribute signupAt:timestamp

If you omit --label, the CLI derives a label from the kind, for example User for user. Entity kinds and attribute keys can contain up to 128 letters, numbers, dashes, and underscores. Labels can be up to 128 characters. A project can have up to 32 entities, and each entity can have up to 32 attributes.

Attributes use these types:

Update an entity's label or attributes:

vercel flags entities update user --label "End user" \
  --add-attribute email:string --remove-attribute legacyId

vercel flags entities update user --set-attribute-type signupAt:timestamp

Removing an attribute or changing its type fails while flags or segments still reference the attribute. Changing an attribute type also removes its existing value labels.

Delete an entity with rm:

vercel flags entities rm device --yes

You can't delete an entity while flags or segments reference it. Remove every reference first, then run vercel flags entities rm.

The vercel flags labels subcommand manages value labels for string and stringArray attributes. Labels map raw values such as IDs to readable names in the dashboard and CLI output.

vercel flags labels ls

vercel flags labels ls user.plan --limit 50

Set or remove one label at a time:

vercel flags labels set user.plan pro "Pro Plan"

vercel flags labels rm user.plan pro

Use apply to change up to 100 labels in one command:

vercel flags labels apply user.plan \
  --set "pro=Pro Plan" --set "enterprise=Enterprise Plan" --remove legacy

You can also pass label operations as a JSON array with --data. Each operation has an operation of upsert or delete, a value, and for upsert a label. --data can't be combined with --set or --remove.

vercel flags labels apply user.plan \
  --data '[{"operation":"upsert","value":"pro","label":"Pro Plan"},{"operation":"delete","value":"legacy"}]'

Removing a label never changes targeting. Rules that reference the raw value keep working.

The vercel flags sdk-keys subcommand manages SDK keys for your project. SDK keys authenticate your application when evaluating flags. You can create keys for different environments and key types.

vercel flags sdk-keys ls

vercel flags sdk-keys create --type server --environment production

vercel flags sdk-keys rm [hash-key]

When you create an SDK key, the output includes:

• Hash key: A truncated identifier shown in the key list
• SDK key: The full key value, shown only at creation time
• Connection string: A flags: URI containing all configuration needed to connect to Vercel Flags

If you don't provide the --environment option, you'll be prompted to select one interactively.

vercel flags list --json, vercel flags versions [flag] --json, vercel flags versions diff [flag] --revision [number] --json, vercel flags rules ls --json, vercel flags segments ls --json, and vercel flags sdk-keys ls --json output JSON for scripting and automation.

The vercel flags override subcommand encrypts flag override values into a secure token. Set the token in the vercel-flag-overrides cookie to override flag evaluation for a session without changing the flag's configuration.

vercel flags override [flag=value ...]

override requires the FLAGS_SECRET environment variable on every invocation (both encryption and --decrypt). The CLI reads FLAGS_SECRET from your process environment or from a .env.local or .env file in the current directory. The value must be a 256-bit base64url-encoded key (32 bytes); this is the same secret your application uses to verify the cookie. If FLAGS_SECRET is missing, the command exits with FLAGS_SECRET not found. Set it in the environment, .env.local, or .env file. Run vercel env pull to populate .env.local from the linked project, or create a matching secret locally.

Pass one or more flag=value arguments to encrypt. The default token expiration is one year; use --expiration to set a different value (for example, 30d).

# Encrypt a single flag override
vercel flags override my-flag=true
 
# Encrypt multiple flag overrides
vercel flags override flag-a=true flag-b=hello
 
# Set a custom expiration
vercel flags override my-flag=42 --expiration 30d

To inspect an existing token, pass --decrypt:

vercel flags override --decrypt <token>

The vercel flags prepare subcommand writes a synthetic @vercel/flags-definitions package into node_modules so that fallback flag definitions are available to your app at runtime without a live flag-service round-trip. It delegates to @vercel/prepare-flags-definitions and uses your environment (process, .env.local, .env) to fetch definitions. If no usable credential is found, the command exits without writing anything.

Most users won't invoke prepare directly; the build pipeline runs it automatically when one of the following is true:

• An environment variable contains a raw SDK key matching vf_server_* or vf_client_*.
• The @flags-sdk/vercel or @vercel/flags-core package is installed in the project.
• VERCEL_FLAGS_EMBED_DEFINITIONS=force-on is set (use force-off to force-skip, or VERCEL_FLAGS_DISABLE_DEFINITION_EMBEDDING=1 to legacy opt-out).

A flags: connection string alone does not trigger the automatic gate, but it is recognized by the preparer once invoked. Run vercel flags prepare directly when you want the build artifact from a connection-string-only setup.

vercel flags prepare

These are options that only apply to the vercel flags command.

The --state option, shorthand -s, filters the list of flags by state when using vercel flags list. Valid values are active and archived. Defaults to active.

vercel flags ls --state archived

The --since option, shorthand -s, sets the start of the time range for vercel flags evaluations. Use a relative duration like 1h, 30m, 2d, or 1w, or an ISO 8601 timestamp. If omitted, the range starts one hour before the command runs.

vercel flags evaluations new-checkout --since 24h

The --until option, shorthand -u, sets the end of the time range for vercel flags evaluations. It accepts the same relative durations and ISO 8601 timestamps as --since. If omitted, the range ends at the current time. The start time must be earlier than the end time.

vercel flags evaluations new-checkout --since 24h --until 1h

The --group-by option selects dimensions for vercel flags evaluations: variant, flag, sdk-key, client, environment, or reason. Repeat it to combine dimensions. Grouping by variant requires a flag argument. Deleted SDK keys appear as their hash.

To find SDK keys still evaluating flags after a key rotation, query the whole project:

vercel flags evaluations --group-by sdk-key --since 24h
vercel flags evaluations new-checkout --group-by sdk-key --group-by client

The --granularity option, shorthand -g, sets the time bucket size for vercel flags evaluations. Supported values are 1m, 5m, 15m, 1h, 4h, and 1d.

If you omit --granularity, the CLI selects a bucket size based on the time range. The minimum bucket size prevents overly detailed queries over long periods:

When you request a bucket smaller than the minimum, the CLI uses the minimum instead. Human-readable output includes a notice, while JSON output reports the adjusted value in granularity.

vercel flags evaluations new-checkout --since 7d --granularity 4h

The --group-by option sets the dimensions vercel flags evaluations groups results by. Supported values are variant, flag, sdk-key, client, environment, and reason. Repeat the option to group by several dimensions. If you omit it, the command groups by variant when you pass a flag, and by flag when you query the whole project. Grouping by variant requires a flag.

vercel flags evaluations new-checkout --group-by environment --group-by reason

The --json option prints machine-readable output for commands that support JSON output, including vercel flags list, vercel flags versions, vercel flags versions diff, vercel flags evaluations, vercel flags rules ls, vercel flags segments ls, vercel flags segments inspect, vercel flags segments create, vercel flags segments update, vercel flags entities ls, vercel flags entities create, vercel flags entities update, every vercel flags labels subcommand, and vercel flags sdk-keys ls.

vercel flags segments inspect beta-users --json

vercel flags versions and vercel flags versions list return up to 20 versions per page by default. Use --limit to request a different page size. The value must be an integer from 1 through 100.

vercel flags labels ls also returns up to 20 lists or labels per page. Use --limit to change the page size and --next to continue from the previous page. For vercel flags labels ls, any positive integer is valid.

vercel flags versions welcome-message --limit 10

The --next option gets the next page from a previous vercel flags list, vercel flags versions, or vercel flags labels ls response. Human-readable output prints a next-page command when another page is available. JSON output returns the next cursor as pagination.next.

vercel flags versions welcome-message --limit 10 --next next_page_cursor

vercel flags labels ls user.plan --limit 50 --next next_page_cursor

vercel flags versions also accepts the deprecated --cursor option as an alias for --next.

The required --revision option selects the revision to compare when using vercel flags versions diff. The selected revision is compared with the immediately preceding revision, so revision 0 can't be diffed.

vercel flags versions diff welcome-message --revision 4

The --kind option, shorthand -k, specifies the type of a new flag when using vercel flags create. Valid values are boolean, string, number, and json. Defaults to boolean.

vercel flags create layout-config --kind json \
  --variant '{"theme":"light"}'=Light \
  --variant '{"theme":"dark","sidebar":true}'=Dark

The --description option, shorthand -d, sets a description for a new flag when using vercel flags create, or a segment description when using vercel flags segments create or vercel flags segments update.

vercel flags create my-feature --description "Controls the new onboarding flow"

The --hint option sets help text that describes who belongs in a segment when using vercel flags segments create or vercel flags segments update. If you omit --hint while creating a segment, the CLI uses the segment description or label.

vercel flags segments create beta-users --label "Beta users" \
  --hint "Users enrolled in the beta program"

The --data option provides full segment data JSON when using vercel flags segments create, or replaces segment data when using vercel flags segments update. The JSON object can include rules, include, and exclude fields. When using vercel flags labels apply, --data provides a JSON array of label operations instead.

vercel flags segments update staff \
  --data '{"rules":[],"include":{"user":{"email":[{"value":"me@company.com"}]}},"exclude":{}}'

When updating a segment, if you combine --data with --add or --remove, the CLI applies the add and remove operations to the provided JSON before saving the segment.

The --add option, shorthand -a, adds segment criteria when using vercel flags segments create or vercel flags segments update. The --remove option removes segment criteria when using vercel flags segments update.

vercel flags segments update beta-users --add include:user.id=user_789 \
  --remove include:user.id=user_123

For rules, use rule:ENTITY.ATTRIBUTE:OPERATOR:VALUE. See available rule operators for OPERATOR values. To remove a rule by ID, use --remove rule:RULE_ID.

When using vercel flags labels apply, --remove takes a raw attribute value and removes its label.

The --attribute option, shorthand -a, adds an attribute as KEY:TYPE when using vercel flags entities create. Repeat the option to add multiple attributes. See entities for the list of types.

vercel flags entities create team --attribute id:string --attribute features:stringArray

The --add-attribute, --remove-attribute, and --set-attribute-type options change an entity when using vercel flags entities update. --add-attribute and --set-attribute-type take KEY:TYPE. --remove-attribute takes only the key. Each option is repeatable.

vercel flags entities update user --add-attribute email:string \
  --set-attribute-type signupAt:timestamp --remove-attribute legacyId

--remove-attribute and --set-attribute-type fail while flags or segments still reference the attribute. Changing a type also removes the attribute's value labels.

The --set option creates or replaces a value label as VALUE=LABEL when using vercel flags labels apply. Repeat the option to set multiple labels.

vercel flags labels apply user.plan --set "pro=Pro Plan" --set "enterprise=Enterprise Plan"

The --condition option, shorthand -c, defines a condition when using vercel flags rules add or replaces all conditions when using vercel flags rules update. Use ENTITY.ATTRIBUTE:OPERATOR:VALUE for entity attributes or segment:OPERATOR:SEGMENT for reusable segments. See available rule operators for OPERATOR values. Repeat --condition or separate conditions with semicolons to add multiple conditions.

vercel flags rules add my-feature --environment production \
  --condition user.plan:eq:pro --condition team.tier:eq:enterprise \
  --variant on

The --environment option, shorthand -e, specifies the target environment for vercel flags set, vercel flags split, vercel flags rollout, vercel flags enable, vercel flags disable, vercel flags rules, and vercel flags sdk-keys create. When using vercel flags versions or vercel flags versions list, it filters versions by the environment that changed. Valid values are production, preview, and development.

vercel flags set welcome-message --environment production --variant control

The --variant option, shorthand -v, defines variants on vercel flags create, and selects a variant by ID or value on vercel flags update, vercel flags set, vercel flags disable, vercel flags rules add, and vercel flags rules update.

For JSON flags, create variants with --variant '<JSON>' or --variant '<JSON>'=Label. When you update a JSON flag, the selector can be a variant ID or the current JSON value, but not the label.

vercel flags create welcome-message --kind string \
  --variant control="Welcome back" --variant treatment="Start for free"

The --by option selects the entity attribute used for consistent bucketing when using vercel flags split, vercel flags rollout, vercel flags rules add, or vercel flags rules update. Use the format <entity.attribute>, such as user.id.

vercel flags rollout redesigned-checkout --environment production --by user.id \
  --stage 5,6h --stage 25,12h

The --weight option, shorthand -w, adds a variant weight when using vercel flags split, vercel flags rules add, or vercel flags rules update. Use the format VARIANT=WEIGHT, and repeat the option for every variant. VARIANT can be a variant ID or value. Vercel Flags normalizes weights into percentages, and a weight of 0 excludes a variant from receiving traffic.

vercel flags split ai-summary-model --environment production --by user.id \
  --default-variant stable --weight stable=95 --weight candidate=5

The --from-variant, --to-variant, and --default-variant options control which variants a rollout uses. --from-variant is the current variant, --to-variant is the rollout target, and --default-variant is served when the bucketing attribute is missing.

The --default-variant option also applies to vercel flags split and split outcomes for vercel flags rules. Boolean splits default to the false variant. For String, Number, and JSON splits, pass --default-variant to choose the fallback variant served when the split's bucketing attribute is missing. The split default variant accepts either a variant ID or a variant value.

For Boolean flag rollouts, these values default to false, true, and false. For String, Number, and JSON flag rollouts, pass them explicitly. Each option accepts either a variant ID or a variant value. The rollout options also apply to rollout outcomes for vercel flags rules.

vercel flags rollout welcome-message --environment production --by user.id \
  --from-variant control --to-variant treatment --default-variant control \
  --stage 10,2h --stage 50,12h

The --value option sets the new value for a variant when using vercel flags update. For JSON flags, --value must be valid JSON. Boolean variants can keep their existing true or false value, but they cannot be changed to a different boolean value.

vercel flags update welcome-message --variant control --value welcome-back

The --label option, shorthand -l, sets a variant label when using vercel flags update, a segment label when using vercel flags segments create or vercel flags segments update, an entity label when using vercel flags entities create or vercel flags entities update, or an SDK key label when using vercel flags sdk-keys create.

vercel flags update welcome-message --variant control --label "Welcome back"

The --message option sets an optional revision message when using vercel flags update, vercel flags set, vercel flags split, vercel flags rollout, vercel flags enable, vercel flags disable, vercel flags rules add, vercel flags rules update, vercel flags rules move, or vercel flags rules rm.

vercel flags set welcome-message -e preview --variant control \
  --message "Keep preview on control"

The --stage option, shorthand -s, adds a rollout stage when using vercel flags rollout, vercel flags rules add, or vercel flags rules update. Each stage uses the format PERCENTAGE,DURATION, for example 5,6h. Repeat --stage to build a longer schedule.

vercel flags rollout redesigned-checkout --environment production --by user.id \
  --stage 5,6h --stage 10,6h --stage 25,12h --stage 50,1d

The --final-percentage option sets the percentage of the rollout variant that is served indefinitely after the last stage finishes when using vercel flags rollout, vercel flags rules add, or vercel flags rules update. Pass a value from 0 to 100 with up to three decimal places. New rollouts default to 100. If you rerun a command without --final-percentage, the CLI keeps the current value.

vercel flags rollout redesigned-checkout --environment production --by user.id \
  --stage 5,6h --stage 25,12h --final-percentage 50

Final percentages below 100% require @vercel/flags-core version 1.9.0 or later. Older SDK versions ignore the final percentage and finish the rollout at 100% of the target variant.

The --start option controls when a rollout begins when using vercel flags rollout, vercel flags rules add, or vercel flags rules update. Use now, a future relative duration like 1h, or an ISO 8601 datetime.

vercel flags rollout welcome-message --environment production --by user.id \
  --from-variant control --to-variant treatment --default-variant control \
  --stage 10,2h --stage 50,12h --start 2026-04-16T09:00:00Z

The --position option, shorthand -p, sets the 1-based position for a conditional rule when using vercel flags rules add or vercel flags rules move. If you omit --position when adding a rule, the CLI adds the rule at the end.

vercel flags rules move my-feature rule_123 --environment production \
  --position 1

The --type option specifies the type of SDK key when using vercel flags sdk-keys create.

vercel flags sdk-keys create --type server --environment production

The --yes option, shorthand -y, skips the confirmation prompt when archiving, unarchiving, or deleting a flag, deleting a segment, deleting an entity, or deleting an SDK key.

vercel flags archive my-feature --yes

The --expiration option sets how long an encrypted override token returned by vercel flags override stays valid. Accepts any duration string parseable by setExpirationTime in jose (for example, 30d, 12h, 90d). Defaults to 1y.

vercel flags override my-flag=42 --expiration 30d

The --decrypt option switches vercel flags override from encrypt mode to decrypt mode. Pass the encrypted override token and the CLI prints the override payload as JSON. Requires the same FLAGS_SECRET used to encrypt the token.

vercel flags override --decrypt <token>

The following global options can be passed when using the vercel flags command:

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --no-color
• --non-interactive
• --scope
• --team
• --token
• --version

For more information on global options and their usage, refer to the options section.