From 675390aca31ff6020dba2bf0ee9b69fc0ba24899 Mon Sep 17 00:00:00 2001 From: Vincent Derks Date: Wed, 9 Sep 2026 11:32:55 +0200 Subject: [PATCH 1/4] docs(skills): separate flag management from SDK setup --- skills/flags-sdk/SKILL.md | 20 ++++++++++++++------ skills/flags-sdk/references/providers.md | 4 ++-- 2 files changed, 16 insertions(+), 8 deletions(-) diff --git a/skills/flags-sdk/SKILL.md b/skills/flags-sdk/SKILL.md index 51a31445..74d5c8d2 100644 --- a/skills/flags-sdk/SKILL.md +++ b/skills/flags-sdk/SKILL.md @@ -59,6 +59,14 @@ export const exampleFlag = flag({ > **Version note**: The SDK is published as `flags` (renamed from `@vercel/flags`; that old name still appears in changelog history). `flags` 4.2.0+ accepts the adapter factory by reference (`adapter: vercelAdapter`) and resolves it once per declaration. Older versions require calling it (`adapter: vercelAdapter()`). The called form still works on new versions, so prefer the shorthand unless you're targeting `flags` < 4.2.0. +## CLI-only flag management + +Managing remote flags with `vercel flags` requires an authenticated CLI, but not SDK packages, Toolbar, Flags Explorer, or `.env.local`. For requests that only inspect or change remote flags, skip app setup and code changes. + +Use `--project ` and `--scope ` to select the target without a local link. If relying on a link, run `vercel project inspect --non-interactive` from the intended directory and confirm its owner and project; a `.vercel/` directory alone does not prove the target. Stop on a mismatch rather than silently relinking. + +CLI authentication is separate from the app's OIDC or SDK key. Pull local credentials only when the app needs local SDK evaluation, not to prepare a CLI flag command. + ## Set up the SDK One-time project setup. Run this when the Flags SDK is not installed yet, or when Toolbar / Flags Explorer / `.env.local` are missing. Skip any step that is already done. @@ -69,7 +77,7 @@ Check the project state to adapt commands and decide which steps you can skip: - Which lockfile is present (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`)? → Adapt all package manager commands accordingly (`pnpm add`, `npm install`, `yarn add`, `bun add`). - Is `flags` in `package.json`? → Skip install (step 1) -- Does `.vercel/` directory exist? → Project is linked, skip `vercel link` in step 2 +- Is the intended project already linked? → Verify its owner and project with `vercel project inspect --non-interactive`; directory existence alone is insufficient. - Does `.env.local` contain `VERCEL_OIDC_TOKEN=` (or a `FLAGS=` SDK key)? → Env vars already pulled, skip step 3 - Is `@vercel/toolbar` in `package.json`? → Skip toolbar setup (step 4) - Does `flags.ts` (or `lib/flags.ts`, `src/flags.ts`) exist? → Skip creating it (step 5) @@ -82,10 +90,10 @@ Check the project state to adapt commands and decide which steps you can skip: pnpm i flags @flags-sdk/vercel ``` -2. **Link the project to Vercel** (required for `vercel flags` and env vars): +2. **Resolve the Vercel project**: > **Prerequisite**: The `vercel flags` commands require the Vercel CLI to be installed and authenticated. If the Vercel CLI is not installed, run `pnpm i -g vercel`. For authentication or linking issues, follow the `vercel-cli` skill if it's already available. If it isn't, suggest the user install it with `npx skills add vercel/vercel@vercel-cli` (don't auto-install it) and rely on `vercel --help` in the meantime. - Check for a `.vercel` directory in the project root. If it doesn't exist, run `vercel link`. + For CLI flag commands, use explicit project/team arguments as described in [CLI-only flag management](#cli-only-flag-management). For local SDK development that needs a link, verify the existing target before creating or changing the link. 3. **Pull environment variables**: If `.env.local` lacks `VERCEL_OIDC_TOKEN=`, follow [Pull environment variables](#pull-environment-variables). @@ -111,7 +119,7 @@ SDK keys (`FLAGS`) are only for apps outside Vercel, custom environments, or fla ## Create a flag -When a user asks you to create or add a feature flag that does not exist on Vercel yet, follow these steps in order. If the flag was already created in the dashboard (the prompt says so, or `vercel flags create` reports the key exists), follow [Add a flag that already exists on Vercel](#add-a-flag-that-already-exists-on-vercel) instead. +When a user asks you to create and integrate a feature flag that does not exist on Vercel yet, follow these steps in order. For a CLI-only creation request, follow [CLI-only flag management](#cli-only-flag-management) and the registration step below; skip app setup and code changes. If the flag was already created in the dashboard (the prompt says so, or `vercel flags create` reports the key exists), follow [Add a flag that already exists on Vercel](#add-a-flag-that-already-exists-on-vercel) instead. ### Before you start @@ -125,7 +133,7 @@ When a user asks you to create or add a feature flag that does not exist on Verc 2. **Register the flag with Vercel**: Run `vercel flags create --kind boolean --description ""`. - Before running `vercel flags create`, verify the project is linked (`.vercel` directory). If missing, run `vercel link` first. + Select the intended project with `--project --scope `, or verify the existing local link as described in [CLI-only flag management](#cli-only-flag-management). 3. **Pull environment variables**: If this is the project's first flag, follow [Pull environment variables](#pull-environment-variables) again; activation created the `FLAGS_SECRET`. @@ -152,7 +160,7 @@ When a user asks you to create or add a feature flag that does not exist on Verc ## Add a flag that already exists on Vercel -Use this flow when the flag was created in the dashboard or by someone else, for example when the prompt says the flag "has already been created" or asks you to run `vercel flags inspect`. Do not run `vercel flags create` for an existing key. +Use this flow when the flag was created in the dashboard or by someone else, for example when the prompt says the flag "has already been created" or asks you to run `vercel flags inspect`. Do not run `vercel flags create` for an existing key. If the user only asks to inspect the flag, follow [CLI-only flag management](#cli-only-flag-management) and read the definition; skip SDK setup and source edits. 1. **Ensure the SDK is set up**: Follow [Set up the SDK](#set-up-the-sdk) if needed. 2. **Read the definition**: Run `vercel flags inspect `. Note the kind, the variants (value and label), the description, and what each environment serves. diff --git a/skills/flags-sdk/references/providers.md b/skills/flags-sdk/references/providers.md index 525499f7..e42df38b 100644 --- a/skills/flags-sdk/references/providers.md +++ b/skills/flags-sdk/references/providers.md @@ -29,7 +29,7 @@ pnpm i flags @flags-sdk/vercel > **Prerequisite**: The `vercel flags` commands require the Vercel CLI to be installed and authenticated. If the Vercel CLI is not installed, run `pnpm i -g vercel`. For authentication or linking issues, follow the `vercel-cli` skill if it's already available. If it isn't, suggest the user install it with `npx skills add vercel/vercel@vercel-cli` (don't auto-install it) and rely on `vercel --help` in the meantime. -Before running any `vercel flags` command, verify the project is linked to Vercel. Check for a `.vercel` directory in the project root. If it doesn't exist, run `vercel link` first. +For CLI-only flag management, use `--project --scope ` without a local link. If relying on a link, verify the owner and project with `vercel project inspect --non-interactive`; a `.vercel/` directory alone is insufficient. SDK packages and local app credentials are not prerequisites for these commands; see [CLI-only flag management](../SKILL.md#cli-only-flag-management). The following steps integrate a flag into an app. 1. Create a flag in the Vercel dashboard or via CLI: `vercel flags create --kind boolean --description ""` 2. Pull env vars: run `vercel env pull` to write the Vercel OIDC token and the Development `FLAGS_SECRET` to `.env.local` ([Pull environment variables](../SKILL.md#pull-environment-variables)). See [Authentication](#how-the-cli-connects-to-the-sdk) for SDK keys. @@ -116,7 +116,7 @@ Outside Vercel, pass the SDK key: `createClient(process.env.FLAGS)`. Unlike `ver ### `vercel flags` CLI -Manage Vercel Flags from the terminal. Install, link, and `vercel env pull` requirements are in [Setup](#setup) above. +Manage Vercel Flags from the terminal with an authenticated CLI and an explicit or verified linked project. SDK installation and `vercel env pull` are app-development steps, not CLI prerequisites (see [Setup](#setup)). For the current subcommand list and options, run `vercel flags --help` or `vercel flags --help`. For CLI-wide contracts (linking, `--non-interactive`, `--yes`, parsing stdout) follow the `vercel-cli` skill. This section covers only what `--help` cannot tell you. From 3445c26746ee3a3a88faf50d0a5d7a5e6fb5bd24 Mon Sep 17 00:00:00 2001 From: Vincent Derks Date: Wed, 9 Sep 2026 13:32:25 +0200 Subject: [PATCH 2/4] docs(skills): restore vercel link step and route CLI-only requests --- skills/flags-sdk/SKILL.md | 12 ++++++------ skills/flags-sdk/references/providers.md | 4 +++- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/skills/flags-sdk/SKILL.md b/skills/flags-sdk/SKILL.md index 74d5c8d2..abe10d0e 100644 --- a/skills/flags-sdk/SKILL.md +++ b/skills/flags-sdk/SKILL.md @@ -20,7 +20,7 @@ The Flags SDK (`flags` npm package) is a feature flags toolkit for Next.js and S - Docs: https://flags-sdk.dev - Repo: https://github.com/vercel/flags -When the user asks to install, configure, or set up feature flags, follow [Set up the SDK](#set-up-the-sdk) (including `vercel env pull` when `.env.local` is missing). When they ask to create or add a flag, follow [Create a flag](#create-a-flag). Do not leave CLI steps as "next steps" for the user — execute them yourself. +When the user asks to install, configure, or set up feature flags, follow [Set up the SDK](#set-up-the-sdk) (including `vercel env pull` when `.env.local` is missing). When they ask to create or add a flag, follow [Create a flag](#create-a-flag). When they only ask to inspect or change remote flags, follow [CLI-only flag management](#cli-only-flag-management). Do not leave CLI steps as "next steps" for the user — execute them yourself. ## Core concepts @@ -63,7 +63,7 @@ export const exampleFlag = flag({ Managing remote flags with `vercel flags` requires an authenticated CLI, but not SDK packages, Toolbar, Flags Explorer, or `.env.local`. For requests that only inspect or change remote flags, skip app setup and code changes. -Use `--project ` and `--scope ` to select the target without a local link. If relying on a link, run `vercel project inspect --non-interactive` from the intended directory and confirm its owner and project; a `.vercel/` directory alone does not prove the target. Stop on a mismatch rather than silently relinking. +Use `--project ` and `--scope ` to select the target without a local link. If the CLI rejects `--project`, upgrade it first (`pnpm i -g vercel`). If relying on a link, run `vercel project inspect --non-interactive` from the intended directory and confirm its owner and project; a `.vercel/` directory alone does not prove the target. Stop on a mismatch rather than silently relinking. CLI authentication is separate from the app's OIDC or SDK key. Pull local credentials only when the app needs local SDK evaluation, not to prepare a CLI flag command. @@ -77,7 +77,7 @@ Check the project state to adapt commands and decide which steps you can skip: - Which lockfile is present (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`)? → Adapt all package manager commands accordingly (`pnpm add`, `npm install`, `yarn add`, `bun add`). - Is `flags` in `package.json`? → Skip install (step 1) -- Is the intended project already linked? → Verify its owner and project with `vercel project inspect --non-interactive`; directory existence alone is insufficient. +- Does `vercel project inspect --non-interactive` report the intended owner and project? → Project is linked, skip `vercel link` in step 2. A `.vercel/` directory alone does not prove a link. - Does `.env.local` contain `VERCEL_OIDC_TOKEN=` (or a `FLAGS=` SDK key)? → Env vars already pulled, skip step 3 - Is `@vercel/toolbar` in `package.json`? → Skip toolbar setup (step 4) - Does `flags.ts` (or `lib/flags.ts`, `src/flags.ts`) exist? → Skip creating it (step 5) @@ -90,10 +90,10 @@ Check the project state to adapt commands and decide which steps you can skip: pnpm i flags @flags-sdk/vercel ``` -2. **Resolve the Vercel project**: +2. **Link the project to Vercel** (required for `vercel env pull` and local OIDC token refresh): > **Prerequisite**: The `vercel flags` commands require the Vercel CLI to be installed and authenticated. If the Vercel CLI is not installed, run `pnpm i -g vercel`. For authentication or linking issues, follow the `vercel-cli` skill if it's already available. If it isn't, suggest the user install it with `npx skills add vercel/vercel@vercel-cli` (don't auto-install it) and rely on `vercel --help` in the meantime. - For CLI flag commands, use explicit project/team arguments as described in [CLI-only flag management](#cli-only-flag-management). For local SDK development that needs a link, verify the existing target before creating or changing the link. + Run `vercel project inspect --non-interactive`. If it reports `link_required`, run `vercel link`. If it reports a different owner or project than intended, stop and ask the user instead of relinking. `vercel flags` commands do not need the link when you pass `--project` and `--scope`; see [CLI-only flag management](#cli-only-flag-management). 3. **Pull environment variables**: If `.env.local` lacks `VERCEL_OIDC_TOKEN=`, follow [Pull environment variables](#pull-environment-variables). @@ -123,7 +123,7 @@ When a user asks you to create and integrate a feature flag that does not exist ### Before you start -- Complete [Set up the SDK](#set-up-the-sdk) first if packages, Vercel link, `.env.local`, Toolbar, `flags.ts`, or Flags Explorer are missing. Skip steps that are already done. +- For app integration, complete [Set up the SDK](#set-up-the-sdk) first if packages, Vercel link, `.env.local`, Toolbar, `flags.ts`, or Flags Explorer are missing. Skip steps that are already done. For a CLI-only request, skip this checklist and go to step 2. - Does `.env.local` contain `VERCEL_OIDC_TOKEN=`? → Env vars already pulled; see [Pull environment variables](#pull-environment-variables) if local evaluation fails with an authentication error. - Does `flags.ts` (or `lib/flags.ts`, `src/flags.ts`) exist? → Add to it rather than creating from scratch. diff --git a/skills/flags-sdk/references/providers.md b/skills/flags-sdk/references/providers.md index e42df38b..72f298b2 100644 --- a/skills/flags-sdk/references/providers.md +++ b/skills/flags-sdk/references/providers.md @@ -29,7 +29,9 @@ pnpm i flags @flags-sdk/vercel > **Prerequisite**: The `vercel flags` commands require the Vercel CLI to be installed and authenticated. If the Vercel CLI is not installed, run `pnpm i -g vercel`. For authentication or linking issues, follow the `vercel-cli` skill if it's already available. If it isn't, suggest the user install it with `npx skills add vercel/vercel@vercel-cli` (don't auto-install it) and rely on `vercel --help` in the meantime. -For CLI-only flag management, use `--project --scope ` without a local link. If relying on a link, verify the owner and project with `vercel project inspect --non-interactive`; a `.vercel/` directory alone is insufficient. SDK packages and local app credentials are not prerequisites for these commands; see [CLI-only flag management](../SKILL.md#cli-only-flag-management). The following steps integrate a flag into an app. +For CLI-only flag management, use `--project --scope ` without a local link. If relying on a link, verify the owner and project with `vercel project inspect --non-interactive`; a `.vercel/` directory alone is insufficient. SDK packages and local app credentials are not prerequisites for these commands; see [CLI-only flag management](../SKILL.md#cli-only-flag-management). + +The following steps integrate a flag into an app. They need a linked project for `vercel env pull`: if `vercel project inspect --non-interactive` reports `link_required`, run `vercel link` first. 1. Create a flag in the Vercel dashboard or via CLI: `vercel flags create --kind boolean --description ""` 2. Pull env vars: run `vercel env pull` to write the Vercel OIDC token and the Development `FLAGS_SECRET` to `.env.local` ([Pull environment variables](../SKILL.md#pull-environment-variables)). See [Authentication](#how-the-cli-connects-to-the-sdk) for SDK keys. From 9f67eb50eff06954ad6a980a19f5614d193cc66d Mon Sep 17 00:00:00 2001 From: Vincent Derks Date: Wed, 9 Sep 2026 17:43:44 +0200 Subject: [PATCH 3/4] docs(skills): keep setup first and define CLI-only requests Move the CLI-only section below the setup and create flows, define when a request is CLI-only, and describe link verification once under Project targeting (EXP-3453). --- skills/flags-sdk/SKILL.md | 34 +++++++++++++----------- skills/flags-sdk/references/providers.md | 8 +++--- 2 files changed, 21 insertions(+), 21 deletions(-) diff --git a/skills/flags-sdk/SKILL.md b/skills/flags-sdk/SKILL.md index abe10d0e..271da87f 100644 --- a/skills/flags-sdk/SKILL.md +++ b/skills/flags-sdk/SKILL.md @@ -20,7 +20,7 @@ The Flags SDK (`flags` npm package) is a feature flags toolkit for Next.js and S - Docs: https://flags-sdk.dev - Repo: https://github.com/vercel/flags -When the user asks to install, configure, or set up feature flags, follow [Set up the SDK](#set-up-the-sdk) (including `vercel env pull` when `.env.local` is missing). When they ask to create or add a flag, follow [Create a flag](#create-a-flag). When they only ask to inspect or change remote flags, follow [CLI-only flag management](#cli-only-flag-management). Do not leave CLI steps as "next steps" for the user — execute them yourself. +When the user asks to install, configure, or set up feature flags, follow [Set up the SDK](#set-up-the-sdk) (including `vercel env pull` when `.env.local` is missing). When they ask to create or add a flag, follow [Create a flag](#create-a-flag). A request is CLI-only when the user asks to inspect or change a remote flag and asks for no code change; then follow [CLI-only flag management](#cli-only-flag-management). Inside an app repository, default to the full flow. Do not leave CLI steps as "next steps" for the user — execute them yourself. ## Core concepts @@ -59,14 +59,6 @@ export const exampleFlag = flag({ > **Version note**: The SDK is published as `flags` (renamed from `@vercel/flags`; that old name still appears in changelog history). `flags` 4.2.0+ accepts the adapter factory by reference (`adapter: vercelAdapter`) and resolves it once per declaration. Older versions require calling it (`adapter: vercelAdapter()`). The called form still works on new versions, so prefer the shorthand unless you're targeting `flags` < 4.2.0. -## CLI-only flag management - -Managing remote flags with `vercel flags` requires an authenticated CLI, but not SDK packages, Toolbar, Flags Explorer, or `.env.local`. For requests that only inspect or change remote flags, skip app setup and code changes. - -Use `--project ` and `--scope ` to select the target without a local link. If the CLI rejects `--project`, upgrade it first (`pnpm i -g vercel`). If relying on a link, run `vercel project inspect --non-interactive` from the intended directory and confirm its owner and project; a `.vercel/` directory alone does not prove the target. Stop on a mismatch rather than silently relinking. - -CLI authentication is separate from the app's OIDC or SDK key. Pull local credentials only when the app needs local SDK evaluation, not to prepare a CLI flag command. - ## Set up the SDK One-time project setup. Run this when the Flags SDK is not installed yet, or when Toolbar / Flags Explorer / `.env.local` are missing. Skip any step that is already done. @@ -77,7 +69,7 @@ Check the project state to adapt commands and decide which steps you can skip: - Which lockfile is present (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`)? → Adapt all package manager commands accordingly (`pnpm add`, `npm install`, `yarn add`, `bun add`). - Is `flags` in `package.json`? → Skip install (step 1) -- Does `vercel project inspect --non-interactive` report the intended owner and project? → Project is linked, skip `vercel link` in step 2. A `.vercel/` directory alone does not prove a link. +- Is the project linked? → Verify as described in [Project targeting](#project-targeting), then skip `vercel link` in step 2 - Does `.env.local` contain `VERCEL_OIDC_TOKEN=` (or a `FLAGS=` SDK key)? → Env vars already pulled, skip step 3 - Is `@vercel/toolbar` in `package.json`? → Skip toolbar setup (step 4) - Does `flags.ts` (or `lib/flags.ts`, `src/flags.ts`) exist? → Skip creating it (step 5) @@ -91,9 +83,9 @@ Check the project state to adapt commands and decide which steps you can skip: ``` 2. **Link the project to Vercel** (required for `vercel env pull` and local OIDC token refresh): - > **Prerequisite**: The `vercel flags` commands require the Vercel CLI to be installed and authenticated. If the Vercel CLI is not installed, run `pnpm i -g vercel`. For authentication or linking issues, follow the `vercel-cli` skill if it's already available. If it isn't, suggest the user install it with `npx skills add vercel/vercel@vercel-cli` (don't auto-install it) and rely on `vercel --help` in the meantime. + > **Prerequisite**: The Vercel CLI must be installed and authenticated. If it is not installed, run `pnpm i -g vercel`. For authentication or linking issues, follow the `vercel-cli` skill if it's already available. If it isn't, suggest the user install it with `npx skills add vercel/vercel@vercel-cli` (don't auto-install it) and rely on `vercel --help` in the meantime. - Run `vercel project inspect --non-interactive`. If it reports `link_required`, run `vercel link`. If it reports a different owner or project than intended, stop and ask the user instead of relinking. `vercel flags` commands do not need the link when you pass `--project` and `--scope`; see [CLI-only flag management](#cli-only-flag-management). + Verify the link as described in [Project targeting](#project-targeting). If the project is not linked, run `vercel link`. 3. **Pull environment variables**: If `.env.local` lacks `VERCEL_OIDC_TOKEN=`, follow [Pull environment variables](#pull-environment-variables). @@ -119,11 +111,11 @@ SDK keys (`FLAGS`) are only for apps outside Vercel, custom environments, or fla ## Create a flag -When a user asks you to create and integrate a feature flag that does not exist on Vercel yet, follow these steps in order. For a CLI-only creation request, follow [CLI-only flag management](#cli-only-flag-management) and the registration step below; skip app setup and code changes. If the flag was already created in the dashboard (the prompt says so, or `vercel flags create` reports the key exists), follow [Add a flag that already exists on Vercel](#add-a-flag-that-already-exists-on-vercel) instead. +When a user asks you to create or add a feature flag that does not exist on Vercel yet, follow these steps in order. For a [CLI-only request](#cli-only-flag-management), run step 2 only. If the flag was already created in the dashboard (the prompt says so, or `vercel flags create` reports the key exists), follow [Add a flag that already exists on Vercel](#add-a-flag-that-already-exists-on-vercel) instead. ### Before you start -- For app integration, complete [Set up the SDK](#set-up-the-sdk) first if packages, Vercel link, `.env.local`, Toolbar, `flags.ts`, or Flags Explorer are missing. Skip steps that are already done. For a CLI-only request, skip this checklist and go to step 2. +- Complete [Set up the SDK](#set-up-the-sdk) first if packages, Vercel link, `.env.local`, Toolbar, `flags.ts`, or Flags Explorer are missing. Skip steps that are already done. - Does `.env.local` contain `VERCEL_OIDC_TOKEN=`? → Env vars already pulled; see [Pull environment variables](#pull-environment-variables) if local evaluation fails with an authentication error. - Does `flags.ts` (or `lib/flags.ts`, `src/flags.ts`) exist? → Add to it rather than creating from scratch. @@ -133,7 +125,7 @@ When a user asks you to create and integrate a feature flag that does not exist 2. **Register the flag with Vercel**: Run `vercel flags create --kind boolean --description ""`. - Select the intended project with `--project --scope `, or verify the existing local link as described in [CLI-only flag management](#cli-only-flag-management). + Target the project as described in [Project targeting](#project-targeting). 3. **Pull environment variables**: If this is the project's first flag, follow [Pull environment variables](#pull-environment-variables) again; activation created the `FLAGS_SECRET`. @@ -160,7 +152,7 @@ When a user asks you to create and integrate a feature flag that does not exist ## Add a flag that already exists on Vercel -Use this flow when the flag was created in the dashboard or by someone else, for example when the prompt says the flag "has already been created" or asks you to run `vercel flags inspect`. Do not run `vercel flags create` for an existing key. If the user only asks to inspect the flag, follow [CLI-only flag management](#cli-only-flag-management) and read the definition; skip SDK setup and source edits. +Use this flow when the flag was created in the dashboard or by someone else, for example when the prompt says the flag "has already been created" or asks you to run `vercel flags inspect`. Do not run `vercel flags create` for an existing key. For a [CLI-only request](#cli-only-flag-management), run step 2 only. 1. **Ensure the SDK is set up**: Follow [Set up the SDK](#set-up-the-sdk) if needed. 2. **Read the definition**: Run `vercel flags inspect `. Note the kind, the variants (value and label), the description, and what each environment serves. @@ -182,6 +174,16 @@ Use this flow when the flag was created in the dashboard or by someone else, for ``` 5. **Use the flag** as in [Create a flag](#create-a-flag) step 5. +## CLI-only flag management + +Managing remote flags with `vercel flags` requires an authenticated CLI, but not SDK packages, Toolbar, Flags Explorer, or `.env.local`. For a CLI-only request, skip app setup and code changes. + +CLI authentication is separate from the app's OIDC or SDK key. Pull local credentials only when the app needs local SDK evaluation, not to prepare a CLI flag command. + +### Project targeting + +Use `--project ` and `--scope ` to select the target without a local link. If the CLI rejects `--project`, upgrade it first (`pnpm i -g vercel`). Without these options the commands use the linked project: run `vercel project inspect --non-interactive` and check the reported owner and project name; a `.vercel/` directory alone does not prove a link. If it reports `link_required`, the project is not linked. If the user named a project or team and the output differs, stop and ask instead of relinking. + ## Vercel Flags Vercel Flags is Vercel's feature flags platform. You create and manage flags from the Vercel dashboard or the `vercel flags` CLI, then connect them to your code with the `@flags-sdk/vercel` adapter. `vercelAdapter()` authenticates with the project's Vercel OIDC token and evaluates the configuration of the current environment; SDK keys (`FLAGS`) are for manual authentication only ([SDK Keys](https://vercel.com/docs/flags/vercel-flags/dashboard/sdk-keys)). Activating Vercel Flags creates a `FLAGS_SECRET` per environment for Flags Explorer. diff --git a/skills/flags-sdk/references/providers.md b/skills/flags-sdk/references/providers.md index 72f298b2..a7acbbea 100644 --- a/skills/flags-sdk/references/providers.md +++ b/skills/flags-sdk/references/providers.md @@ -27,11 +27,9 @@ pnpm i flags @flags-sdk/vercel ### Setup -> **Prerequisite**: The `vercel flags` commands require the Vercel CLI to be installed and authenticated. If the Vercel CLI is not installed, run `pnpm i -g vercel`. For authentication or linking issues, follow the `vercel-cli` skill if it's already available. If it isn't, suggest the user install it with `npx skills add vercel/vercel@vercel-cli` (don't auto-install it) and rely on `vercel --help` in the meantime. +> **Prerequisite**: The Vercel CLI must be installed and authenticated. If it is not installed, run `pnpm i -g vercel`. For authentication or linking issues, follow the `vercel-cli` skill if it's already available. If it isn't, suggest the user install it with `npx skills add vercel/vercel@vercel-cli` (don't auto-install it) and rely on `vercel --help` in the meantime. -For CLI-only flag management, use `--project --scope ` without a local link. If relying on a link, verify the owner and project with `vercel project inspect --non-interactive`; a `.vercel/` directory alone is insufficient. SDK packages and local app credentials are not prerequisites for these commands; see [CLI-only flag management](../SKILL.md#cli-only-flag-management). - -The following steps integrate a flag into an app. They need a linked project for `vercel env pull`: if `vercel project inspect --non-interactive` reports `link_required`, run `vercel link` first. +The following steps integrate a flag into an app and need a linked project for `vercel env pull`; verify the link as described in [Project targeting](../SKILL.md#project-targeting). To only inspect or change remote flags, follow [CLI-only flag management](../SKILL.md#cli-only-flag-management) instead. 1. Create a flag in the Vercel dashboard or via CLI: `vercel flags create --kind boolean --description ""` 2. Pull env vars: run `vercel env pull` to write the Vercel OIDC token and the Development `FLAGS_SECRET` to `.env.local` ([Pull environment variables](../SKILL.md#pull-environment-variables)). See [Authentication](#how-the-cli-connects-to-the-sdk) for SDK keys. @@ -118,7 +116,7 @@ Outside Vercel, pass the SDK key: `createClient(process.env.FLAGS)`. Unlike `ver ### `vercel flags` CLI -Manage Vercel Flags from the terminal with an authenticated CLI and an explicit or verified linked project. SDK installation and `vercel env pull` are app-development steps, not CLI prerequisites (see [Setup](#setup)). +Manage Vercel Flags from the terminal with an authenticated CLI and a targeted project ([Project targeting](../SKILL.md#project-targeting)). SDK installation and `vercel env pull` are app-development steps, not CLI prerequisites (see [Setup](#setup)). For the current subcommand list and options, run `vercel flags --help` or `vercel flags --help`. For CLI-wide contracts (linking, `--non-interactive`, `--yes`, parsing stdout) follow the `vercel-cli` skill. This section covers only what `--help` cannot tell you. From bbbb17c6cb86f0a34ef480e727e82b0acfd124dc Mon Sep 17 00:00:00 2001 From: Vincent Derks Date: Thu, 10 Sep 2026 10:29:30 +0200 Subject: [PATCH 4/4] docs(skills): tighten CLI-only trigger and link to CLI reference --- skills/flags-sdk/SKILL.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/skills/flags-sdk/SKILL.md b/skills/flags-sdk/SKILL.md index 271da87f..0dc5c401 100644 --- a/skills/flags-sdk/SKILL.md +++ b/skills/flags-sdk/SKILL.md @@ -20,7 +20,7 @@ The Flags SDK (`flags` npm package) is a feature flags toolkit for Next.js and S - Docs: https://flags-sdk.dev - Repo: https://github.com/vercel/flags -When the user asks to install, configure, or set up feature flags, follow [Set up the SDK](#set-up-the-sdk) (including `vercel env pull` when `.env.local` is missing). When they ask to create or add a flag, follow [Create a flag](#create-a-flag). A request is CLI-only when the user asks to inspect or change a remote flag and asks for no code change; then follow [CLI-only flag management](#cli-only-flag-management). Inside an app repository, default to the full flow. Do not leave CLI steps as "next steps" for the user — execute them yourself. +When the user asks to install, configure, or set up feature flags, follow [Set up the SDK](#set-up-the-sdk) (including `vercel env pull` when `.env.local` is missing). When they ask to create or add a flag, follow [Create a flag](#create-a-flag). A request is CLI-only when the user asks to inspect, create, or change a remote flag and the request involves no code; then follow [CLI-only flag management](#cli-only-flag-management). Inside an app repository, treat an ambiguous request as the full flow. Do not leave CLI steps as "next steps" for the user — execute them yourself. ## Core concepts @@ -69,7 +69,7 @@ Check the project state to adapt commands and decide which steps you can skip: - Which lockfile is present (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`)? → Adapt all package manager commands accordingly (`pnpm add`, `npm install`, `yarn add`, `bun add`). - Is `flags` in `package.json`? → Skip install (step 1) -- Is the project linked? → Verify as described in [Project targeting](#project-targeting), then skip `vercel link` in step 2 +- Is the project linked? → Skip `vercel link` in step 2 - Does `.env.local` contain `VERCEL_OIDC_TOKEN=` (or a `FLAGS=` SDK key)? → Env vars already pulled, skip step 3 - Is `@vercel/toolbar` in `package.json`? → Skip toolbar setup (step 4) - Does `flags.ts` (or `lib/flags.ts`, `src/flags.ts`) exist? → Skip creating it (step 5) @@ -115,7 +115,7 @@ When a user asks you to create or add a feature flag that does not exist on Verc ### Before you start -- Complete [Set up the SDK](#set-up-the-sdk) first if packages, Vercel link, `.env.local`, Toolbar, `flags.ts`, or Flags Explorer are missing. Skip steps that are already done. +- Complete [Set up the SDK](#set-up-the-sdk) first if packages, Vercel link, `.env.local`, Toolbar, `flags.ts`, or Flags Explorer are missing. Skip steps that are already done. Skip this entirely for a [CLI-only request](#cli-only-flag-management). - Does `.env.local` contain `VERCEL_OIDC_TOKEN=`? → Env vars already pulled; see [Pull environment variables](#pull-environment-variables) if local evaluation fails with an authentication error. - Does `flags.ts` (or `lib/flags.ts`, `src/flags.ts`) exist? → Add to it rather than creating from scratch. @@ -176,13 +176,13 @@ Use this flow when the flag was created in the dashboard or by someone else, for ## CLI-only flag management -Managing remote flags with `vercel flags` requires an authenticated CLI, but not SDK packages, Toolbar, Flags Explorer, or `.env.local`. For a CLI-only request, skip app setup and code changes. +Managing remote flags with `vercel flags` requires an authenticated CLI, but not SDK packages, Toolbar, Flags Explorer, or `.env.local`. For a CLI-only request, skip app setup and code changes. Target the project as described in [Project targeting](#project-targeting), then follow [references/providers.md — `vercel flags` CLI](references/providers.md#vercel-flags-cli) for command semantics and safety notes. CLI authentication is separate from the app's OIDC or SDK key. Pull local credentials only when the app needs local SDK evaluation, not to prepare a CLI flag command. ### Project targeting -Use `--project ` and `--scope ` to select the target without a local link. If the CLI rejects `--project`, upgrade it first (`pnpm i -g vercel`). Without these options the commands use the linked project: run `vercel project inspect --non-interactive` and check the reported owner and project name; a `.vercel/` directory alone does not prove a link. If it reports `link_required`, the project is not linked. If the user named a project or team and the output differs, stop and ask instead of relinking. +Use `--project ` and `--scope ` to select the target without a local link. If the CLI rejects `--project`, upgrade it first (`pnpm i -g vercel`). Without these options the commands use the linked project: run `vercel project inspect --non-interactive` and check the reported owner and project name; a `.vercel/` directory alone does not prove a link. If it reports `link_required`, the project is not linked. If the user named a project or team and the output differs, stop and ask instead of relinking. For a CLI-only request in an unlinked directory, prefer `--project` / `--scope` over `vercel link`; if the target project is unknown, ask. ## Vercel Flags