Index of every page on this site: llms.txt
All skills
vercel avatar

/vercel-flags

@e98c352
by vercelvercel/flags631 stars
93
Run it yourself

Feature flags, A/B tests, and gradual rollouts with Vercel Flags, in any app or framework. Use whenever the user is planning, adding, changing, or cleaning up a feature flag, toggle, kill switch, experiment, percentage rollout, or targeting rule, or wants to gate or hide a feature for some users, even before a library or provider is chosen. Covers choosing an integration (Flags SDK, `@vercel/flags-core`, OpenFeature), the Vercel dashboard, the `vercel flags` CLI (create, inspect, set, split, rollout, rules, segments, evaluations, archive, connections), Project Connections, OIDC vs SDK keys, `FLAGS_SECRET`, and Flags Explorer overrides. For `flag()` declarations, adapters, precompute, and the Flags Explorer endpoint in Next.js or SvelteKit code, load the `flags-sdk` skill.

Use this Skill: https://skilld.dev/gh/vercel/flags/vercel-flags

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencescli.md

≈2.8k tokens on demand. Your agent reads this file only when SKILL.md points to it.

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 key in flag() (Flags SDK) or the first argument of evaluate() (@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: options on 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 and generatePermutations enumerate them (Declaring options). When you declare them, keep them equal to the variants inspect shows.
  • 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, and rules add take --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 a User entity with an id attribute 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-variant in the CLI) and a rule that references it is skipped. Verify with evaluations.
  • 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 deduped Date.now() for release-at-a-time rules, is in the flags-sdk skill's provider reference (Attribute types).
  • Timestamp conditions: for Timestamp attributes, --condition accepts gt, lt, gte, lte or the aliases after, before, at-or-after, at-or-before with an ISO 8601 date-time or epoch milliseconds, for example --condition system.time:at-or-after:2026-04-16T09:00:00Z. after and before are exclusive; other operators are rejected. A date-time without a timezone uses the machine's local timezone, so include Z or an offset. --by rejects Timestamp attributes.
  • Authentication: on Vercel, the app authenticates with the project's OIDC token and uses the configuration of the current environment; vercel env pull brings that credential to .env.local for 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 the vercel-flag-overrides cookie and reads FLAGS_SECRET from 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/vercel or @vercel/flags-core and the build can authenticate. This keeps every function on one snapshot and serves as the runtime fallback when the service is unreachable; opt out with VERCEL_FLAGS_DISABLE_DEFINITION_EMBEDDING=1 (Embedded definitions). vercel flags prepare is 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. Run vercel flags connections list --project <source> --scope <team> --non-interactive first and reuse an existing connection. Set up and verify the connection before the consumer app evaluates any connected flag: a client rejected with 401 does not retry and serves defaultValue until the process restarts. After connections add, run list again, then confirm a real read with the consumer's credentials outside the app (for example createClient({ projectId: 'prj_source' }).evaluate('<flag-key>') with node --env-file=.env.local) before adding flag declarations. 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, enable or set the flag in preview, verify on the preview URL, deploy to production, then change production (enable, set, split, or rollout). Each environment keeps its own configuration; preview stays on its current value until you change it.
  • Serve vs define: enable / disable work on boolean flags only. set changes the served variant for any kind. update adds, 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 / disable put the environment in static value mode; its split, rollout, and rules are preserved in the background. targeting enable (use-targeting before CLI 65) switches back to targets and rules mode (Switching between static and rules modes). Run inspect first so you know what the environment serves today.
  • Confirm a change: inspect for the served state, versions for the change history (the dashboard can restore any earlier configuration), evaluations to 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> --json with 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-core before 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, archive the flag. unarchive restores its configuration and history. Keep it archived through the agreed observation period before permanent deletion; rm requires an archived flag and cannot be undone (Archive).
  • Agent runs: archive, unarchive, rm, and update --remove-variant prompt for confirmation. Pass --yes when the user has approved the action.

CLI reference: https://vercel.com/docs/cli/flags

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning4d3 checks · Risk SAFE
  • Gen Agent Trust Hub4d

    This skill is safe and facilitates the management of feature flags using Vercel's official tools and libraries. It includes helpful security guidance, such as advising the agent against printing secrets to logs or chat. The operations involve standard CLI interactions and code modifications consistent with its intended purpose.

  • Socket4d

    No alerts

  • Snyk4d

    Risk: MEDIUM · 1 issue

Signed by skilld at e98c352. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 hours ago.

Activeupdated 3 weeks ago

README badge

README badge for vercel/flags/vercel-flags