Set the default value of a GrowthBook feature flag. The default value is what the SDK returns when no rules match a user — it's the flag's baseline state, not a targeting rule. Changes go through a draft revision and require publishing before they take effect.
All API calls go through the bundled helper: ${CLAUDE_PLUGIN_ROOT}/scripts/gb-call. It needs GB_API_KEY set in env or written to ~/.config/growthbook/.env by /growthbook:gb-setup.
Required inputs
- Flag ID — kebab-case key. Use flag-search to resolve if the user gives a description.
- New default value — must match the flag's
valueType. Always serialized as a string.
Workflow
1. Fetch the flag
gb-call GET /api/v2/features/<flag-id>
Capture valueType and current defaultValue. Show the user the current default so they can confirm the change.
2. Validate the new value
Pre-validate before sending — the API does not catch type mismatches at write time:
valueType |
Valid defaultValue |
|---|---|
boolean |
"true" or "false" (string, not JSON bool) |
number |
Any string that parses as a number: "0", "3.14" |
json |
Any valid JSON string: "{\"key\":\"value\"}" |
string |
Any non-empty string |
If the user's value doesn't match, halt and ask them to fix it. Do not silently coerce.
3. Apply the change via a draft
echo '{"defaultValue":"<string>"}' \
| gb-call PUT /api/v2/features/<flag-id>/revisions/new/default-value -
The new magic version creates a fresh draft or layers onto an existing one atomically. Capture the returned version number.
4. Offer to publish
Ask: "Publish this default-value change now, or leave it as a draft?"
Changing the default value affects every user who matches no rules — this is potentially high-impact. Before publishing, surface the behavior change clearly:
Changing the default from
<old>to<new>will affect all users not matched by any rule. In<env>that's currently<rule-count>rule(s) — users falling through all of them will now get<new>instead of<old>.
Hand off to flag-publish for the publish step.
Guardrails
- Draft version threading. If a version number is already in context from a previous write skill in this session, use it explicitly (e.g.
.../revisions/42/default-value) instead ofnew. This keeps all changes in the same draft. Fall back tonewwhen starting fresh — it auto-creates or reuses the most recently updated open draft. defaultValueis always a string, regardless ofvalueType. The API rejects non-string values."false"for boolean off,"0"for numeric zero,"{}"for an empty JSON object.- Default value ≠ a force rule. The default value applies only when all rules fail to match. If the user wants to serve a specific value to targeted users, they want flag-targeting, not this skill.
- This is potentially high-traffic impact. The default value applies to every unmatched user in every enabled environment. Changing it from the "off" state (e.g.,
"false"→"true") can expose a feature to production traffic if there are no rules. Surface this before publishing. - Changing default value for a boolean flag is equivalent to a global toggle when there are no targeting rules. Confirm the user understands this.
- Type mismatches surface at SDK evaluation time, not at write time. The v2 default-value endpoint accepts any string. A number flag with
defaultValue: "not-a-number"won't error until clients evaluate it.
Endpoints used
GET /api/v2/features/:id— fetch flag to get currentdefaultValueandvalueTypePUT /api/v2/features/:id/revisions/new/default-value(body:{ "defaultValue": "<string>" })
Handoffs
flag-search— if the user gives a description instead of a flag IDflag-targeting— to add or edit rules that serve specific values to targeted usersflag-cleanup— if the flag is no longer needed and should be archivedflag-publish— to publish the draft, handle approval-required (400) and merge conflicts (409)