gb-setup

name	gb-setup
description	Configure GrowthBook API credentials so the other skills can run. Use when the user says "set up growthbook", "configure my api key", "growthbook isn't working", "where do I put my key", or when another skill emits an error pointing here ("GB_API_KEY is not set", "authentication failed"). Writes ~/.config/growthbook/.env with chmod 600 and validates against the live API. For listing flags or running experiments, the domain skills handle that.
allowed-tools	Bash(${CLAUDE_PLUGIN_ROOT}/scripts/gb-call *) Bash(mkdir -p ~/.config/growthbook) Bash(chmod 700 ~/.config/growthbook) Bash(chmod 600 ~/.config/growthbook/.env) Bash(test -f ~/.config/growthbook/.env)

gb-setup

One-skill onboarding for GrowthBook Agent Skills. Walks the user through GB_API_KEY and an optional GB_API_URL for self-hosted. Validates the credentials by hitting the live API, then writes ~/.config/growthbook/.env with chmod 600.

The API key is a Personal Access Token (PAT) tied to a GrowthBook user, so the API attributes any flags or experiments the write skills create to that user automatically — there's no separate owner identifier to configure.

gb-call reads this file when the corresponding environment variables aren't set, so the user gets a one-time config rather than editing their shell rc. Real environment variables always win over the file — useful for CI and one-off overrides.

Resolve the bundled helper for the current client before using it: under the Claude Code plugin it is ${CLAUDE_PLUGIN_ROOT}/scripts/gb-call; under a standalone Agent Skills install it is scripts/gb-call relative to this skill directory. Substitute that resolved command for <gb-call> below.

Workflow

1. Detect current state. Check what's already configured. Don't ask the user for values they already have unless they want to change them.

   test -f ~/.config/growthbook/.env && echo "exists" || echo "missing"
   

   If the file exists, read it with the Read tool, parse the KEY=value lines, and surface a masked summary:

   I see existing config at ~/.config/growthbook/.env:
     GB_API_KEY = gb_pat_****wxyz   (last 4 shown)
     GB_API_URL = (not set — defaults to https://api.growthbook.io)
   
   Want to keep these, update one, or start fresh?
   

   Also note what's in process.env — if the user has shell exports, those will override the file. Surface that ("GB_API_KEY is also set in your shell environment; the file value won't be used unless you unset the shell var.")

2. Collect GB_API_KEY (required). If keeping the existing value, skip. Otherwise, show the transcript-exposure notice first so the user can make an informed choice:

   Before you paste your key: anything you type into this chat may be stored by your agent client and is sent to your configured model provider as part of the conversation. The skill will mask the key in its replies, but the value you paste cannot be masked retroactively. Check your client's storage and retention settings if this is a concern.

   Recommendation: generate a fresh PAT for this plugin rather than reusing your personal admin token. That way you can revoke it independently if anything goes wrong, without affecting your other API access.

   Then ask:

   Paste a Personal Access Token (PAT) or Secret Key. Get one at:

   • Cloud: https://app.growthbook.io/account/personal-access-tokens
   • Self-hosted: https://<your-host>/account/personal-access-tokens

   PATs start with gb_pat_; Secret Keys with secret_. Either works.

   Once captured, never echo the value back in any later step — mask all but the last 4 characters.

3. Ask about self-hosted (optional GB_API_URL).

   Are you using GrowthBook Cloud (api.growthbook.io) or a self-hosted instance?

Guardrails

• Never echo the API key back in plain text. Always mask except for the last 4 characters. The skill's output ends up in the user's terminal and transcript.
• Surface the transcript-exposure risk before the user pastes a key. The value typed into chat may be stored by the agent client and is sent to the configured model provider; the skill cannot retroactively redact it. Always recommend a freshly-scoped PAT over reusing an admin token. This isn't paranoia — it's the right way to handle a workflow that requires a user to paste a secret into a conversational interface.
• Revocation guidance is a real fix, not a footnote. If a key was ever exposed, the only effective remediation is to revoke and rotate it at <host>/account/personal-access-tokens. Surface this whenever the user expresses concern about an old or shared key.
• Directory at 0700 before file write; file at 0600 after. The order matters. The Write tool inherits the user's umask, which on most systems creates files at mode 0644 (world-readable). Locking the directory down first means even the brief window between Write and chmod is not reachable by other users. Then chmod the file as defense in depth. Both steps are non-optional; skipping either turns the PAT into a leak.
• Env vars take precedence over the file. If process.env.GB_API_KEY is set, gb-call ignores the file value. Surface this if both are configured so the user understands what's actually in effect.
• Validate against a real endpoint, not just shape. A token that "looks right" but doesn't work is worse than no token — the user thinks they're set up. GET /api/v1/projects is lightweight, requires auth, and works on every plan tier.
• No owner identifier to collect. The PAT is tied to a GrowthBook user, so the write skills (flag-create, experiment-launch) let the API attribute new flags and experiments to the token's user automatically. Don't prompt for an email or userId during setup.
• Don't strip leading whitespace from line values, but strip trailing. A PAT shouldn't have whitespace at all; if the user pasted one with a trailing newline from a clipboard, strip it. Leading whitespace is unusual enough that surfacing rather than silently fixing is safer.
• Don't write a partial file. If validation fails, halt without touching ~/.config/growthbook/.env. The user re-runs setup; we never overwrite a working config with a broken one.
• Strip trailing slash on . does this too, but doing it here avoids "the file has a slash and the URL has a slash" double-slash bugs in logs.

File format reference

~/.config/growthbook/.env:

GB_API_KEY=gb_pat_abc123def456
GB_API_URL=https://api.your-self-hosted.com

Lines starting with # are comments. Blank lines are ignored. No quoting; values are taken verbatim from the first = to end of line.

Endpoints used

• GET /api/v1/projects — validation only. Lightweight, requires auth, available on every tier.

Handoffs

• The feature-flags skill (flag-search workflow) — natural first call after setup completes (no required inputs, exercises the new config).
• The experiments skill (experiment-brainstorm workflow) — if the org already has stopped experiments, surfaces them immediately.
• Any skill that emits a config-related error points back here.