vercel flags CLI
Manage Vercel Flags from the terminal with an authenticated CLI and a targeted project (Project targeting). SDK installation and vercel env pull are app-development steps, not CLI prerequisites.
For the current subcommand list and options, run vercel flags --help or vercel flags <cmd> --help. For CLI-wide contracts (linking, --non-interactive, --yes, parsing stdout) follow the vercel-cli skill. This file covers only what --help cannot tell you.
How the CLI maps to the app
- Key: the flag slug you pass to the CLI is the
keyinflag()(Flags SDK) or the first argument ofevaluate()(@vercel/flags-core). The flag returns one of the variants you created on Vercel (Run an A/B test). - Kind → type:
inspect <key>prints the kind and variants.boolean→flag<boolean>(),string→flag<string>(),number→flag<number>(),json→flag<YourType>(). The kind is fixed at creation and cannot be changed (Flag types). - Variants →
options:optionson a Flags SDK declaration are optional. They give Flags Explorer a dropdown, pre-fill the dashboard when a draft is promoted, and let precompute serialize values andgeneratePermutationsenumerate them (Declaring options). When you declare them, keep them equal to the variantsinspectshows. defaultValue: a flag that is archived, or declared in code but not created on Vercel (a draft), evaluates to its fallback. Without one, Flags SDK evaluation throws (Archive, Drafts).- Targeting attributes:
split,rollout, andrules addtake--by <entity>.<attribute>(and--condition <entity>.<attribute>:<op>:<value>). Define the entity and attribute under Flags → Entities first, and return the same names from the app's evaluation context; the docs use aUserentity with anidattribute and--by user.id(Roll out a feature, Entities). When the attribute is missing from the context, a split or rollout serves its fallback variant (--default-variantin the CLI) and a rule that references it is skipped. Verify withevaluations. - Attribute types: each attribute is a String, Number, Boolean, String Array, or Timestamp, and the app must send a matching value (Entities). Timestamp is a Unix epoch in milliseconds as a number. How to return each type from
identify(), including a dedupedDate.now()for release-at-a-time rules, is in theflags-sdkskill's provider reference (Attribute types). - Timestamp conditions: for Timestamp attributes,
--conditionacceptsgt,lt,gte,lteor the aliasesafter,before,at-or-after,at-or-beforewith an ISO 8601 date-time or epoch milliseconds, for example--condition system.time:at-or-after:2026-04-16T09:00:00Z.afterandbeforeare exclusive; other operators are rejected. A date-time without a timezone uses the machine's local timezone, so includeZor an offset.--byrejects Timestamp attributes. - Authentication: on Vercel, the app authenticates with the project's OIDC token and uses the configuration of the current environment;
vercel env pullbrings that credential to.env.localfor local development. For another same-team project's flags, use Project Connections with the consumer project's OIDC token. SDK keys (FLAGS) are for manual authentication: apps outside Vercel, selecting an environment explicitly, or reading flags across teams. Each SDK key is scoped to one environment and its full value is shown once, at creation (Getting started, SDK Keys). - Overrides: Flags Explorer stores overrides in a cookie signed with
FLAGS_SECRET; flags declared with the Flags SDK honour it automatically (Handling overrides).vercel flags override <key>=<value>produces the same token for thevercel-flag-overridescookie and readsFLAGS_SECRETfrom the environment or.env.local, so use the secret of the environment you test against (see Credentials). - Embedded definitions: Vercel builds fetch the flag definitions once and bundle them into the deployment when the project uses
@flags-sdk/vercelor@vercel/flags-coreand the build can authenticate. This keeps every function on one snapshot and serves as the runtime fallback when the service is unreachable; opt out withVERCEL_FLAGS_DISABLE_DEFINITION_EMBEDDING=1(Embedded definitions).vercel flags prepareis the same step for builds that run outside Vercel.
Project Connections
Connections grant a consumer project read access to a source project's flags within the same team. Use Vercel CLI 63.0.0 or later. Run vercel flags connections --help for commands and options, even if connections are absent from the top-level help in an older release.
Confirm the source project, consumer project, and team before creating a connection. Reuse an existing connection. Creation requires team Member or Owner access, or Project Admin access on the source project, plus permission to view the consumer project. See required permissions.
Configure the consumer with @flags-sdk/vercel 1.6.0 or later and createVercelAdapter({ projectId: 'prj_source' }), or @vercel/flags-core 1.11.0 or later and createClient({ projectId: 'prj_source' }). Replace prj_source with the source project's ID. Follow the SDK connection example or the core guide. Do not create an SDK key for a connection; link to the consumer project and run vercel env pull for local OIDC credentials. The consumer's token selects the source environment, with custom environments mapped to preview.
Lifecycle and safety
The docs describe these flows end to end: Roll out a feature, Run an A/B test. For cleanup, follow the deployment and evaluation checks below before archiving.
- Promote: deploy the code to preview,
enableorsetthe flag in preview, verify on the preview URL, deploy to production, then change production (enable,set,split, orrollout). Each environment keeps its own configuration; preview stays on its current value until you change it. - Serve vs define:
enable/disablework on boolean flags only.setchanges the served variant for any kind.updateadds, removes, or renames variants and does not change what is served. A variant can only be removed when no environment configuration or rule references it, including rules that are stored but not active (Deleting a variant). - Static value vs targeting:
set/enable/disableput the environment in static value mode; its split, rollout, and rules are preserved in the background.targeting enable(use-targetingbefore CLI 65) switches back to targets and rules mode (Switching between static and rules modes). Runinspectfirst so you know what the environment serves today. - Confirm a change:
inspectfor the served state,versionsfor the change history (the dashboard can restore any earlier configuration),evaluationsto confirm traffic reaches the new variant or to check whether a flag is still evaluated before archiving (Evaluation metrics). Local development evaluates the Development environment configuration. - Deploy removal first: search for the flag key and its camelCase name, remove the declaration and conditionals, verify in preview, and complete the rollout to production and every other environment using the flag. A merged PR or preview deployment is not sufficient. Older deployments can still evaluate it through Skew Protection: inspect the project's configured maximum age and account for longer-lived traffic, including crawler exceptions, rather than assuming a fixed 24 or 48 hours.
- Verify no evaluations: before archiving, use
vercel flags evaluations <flag> --since <window> --jsonwith the explicit project/team target. Require no evaluations over an observation window after rollout that covers the applicable Skew Protection period. Check that the returned time range covers the window and the data is not truncated. Clients using@vercel/flags-corebefore 1.6.0 do not report evaluations, so verify reporting coverage; an empty result alone does not prove disuse (Evaluation metrics). If evaluations continue, reporting coverage is unknown, or the window has not elapsed, leave the flag active. - Archive before delete: only after those checks pass,
archivethe flag.unarchiverestores its configuration and history. Keep it archived through the agreed observation period before permanent deletion;rmrequires an archived flag and cannot be undone (Archive). - Agent runs:
archive,unarchive,rm, andupdate --remove-variantprompt for confirmation. Pass--yeswhen the user has approved the action.
CLI reference: https://vercel.com/docs/cli/flags