# Agent Statsig > Manage Statsig feature gates, dynamic configs, experiments, segments, and tags. Use when the user asks about feature flags, A/B tests, rollouts, targeting rules, or any Statsig entity. - Skill: `shhac/agent-statsig` (Agent Skill) - Install (CLI): `npx skillmds@latest add shhac/agent-statsig` - Raw SKILL.md: https://api.skillmd.com/api/skills/shhac/agent-statsig/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: shhac (https://skillmd.com/u/shhac) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/shhac/agent-statsig --- # agent-statsig — Statsig Feature Flag CLI Manage Statsig feature gates, dynamic configs, experiments, and segments via the Console API. ## When to Use - User asks about a feature gate, feature flag, or rollout - User wants to check, modify, or create targeting rules - User asks about experiment status or wants to start/ship/abandon experiments - User asks about dynamic config values or wants to modify them - User wants to manage segment membership - User wants to organize entities with tags ## Process ### Always read before writing 1. **Inspect first**: Run `agent-statsig gate get ` (or config/experiment/segment get) to understand the current state before making changes. Gets default to NDJSON; pass `--format json` for a pretty object. 2. **Check rules**: Run `gate rule list ` to see rule IDs before updating/removing rules 3. **Validate criteria**: Run `gate criteria` if unsure which condition types or operators to use ### Using tags When creating gates, configs, or experiments, apply appropriate tags if the user's intent suggests a category (e.g., "mobile feature" → use `--tag mobile` if such a tag exists). Check available tags with `tag list` first. Tags must exist before they can be applied — create missing tags with `tag create` first. ### Making changes 1. Read the current state 2. Identify what needs to change (add rule, modify values, change rollout %) 3. Make the change with the appropriate command 4. Verify by reading again Config-level writes (`config update`, `schema set/clear`, `value set`, `rule add`) accept `--dry-run` to have the API validate the change without persisting it — useful before risky edits. ### Error handling All errors are JSON to stderr with a classification: - `fixable_by: agent` — you made a typo or used wrong syntax. Read the hint and retry. - `fixable_by: human` — credentials or permissions issue. Tell the user. - `fixable_by: retry` — transient error. Wait and retry once. ## Quick Reference ```bash # Explore (safe, read-only) agent-statsig gate list [--search ] [--tag ] agent-statsig gate get ... # 1..N ids, NDJSON default; @unresolved for misses agent-statsig config get ... agent-statsig experiment get ... agent-statsig segment get ... # Modify gates agent-statsig gate enable agent-statsig gate disable agent-statsig gate rollout --percent 50 agent-statsig gate rule add --name "Rule" --criteria email --value user@co.com agent-statsig gate rule update --rule --add-value new@co.com agent-statsig gate rule remove --rule agent-statsig gate rule move --rule --position # also on config rule # --rule matches by ID first, then unique rule name; ambiguous names error with # the candidate IDs. Add --by-id to disable name matching. # Modify configs (return values validated against schema) agent-statsig config rule add --name "Rule" --criteria email --value user@co.com --return-value '{"key":"val"}' agent-statsig config schema get agent-statsig config schema set '{"type":"object","required":["key"]}' agent-statsig config value set '{"key":"val"}' # defaultValue (no-rule fallback) # Experiment lifecycle agent-statsig experiment start agent-statsig experiment ship --group --reason "text" agent-statsig experiment abandon --reason "text" # Segment IDs agent-statsig segment ids add --id user1 --id user2 agent-statsig segment ids remove --id user1 # Manage tags agent-statsig tag list agent-statsig tag create [--description ] [--is-core] agent-statsig tag get agent-statsig tag update [--name ] [--description ] [--is-core] agent-statsig tag delete # Apply tags when creating/updating entities agent-statsig gate create --tag agent-statsig config create --tag agent-statsig experiment create --tag agent-statsig gate update '{}' --tag ``` ## Detailed Reference For full command details with examples, run per-entity usage: ```bash agent-statsig gate usage agent-statsig config usage agent-statsig experiment usage agent-statsig segment usage agent-statsig tag usage agent-statsig usage # top-level overview ``` ## Output and Debug ### Get contract `get ...` accepts one or more ids and returns one NDJSON line per id, in input order. An unresolvable id emits `{"@unresolved":{"id","reason","fixable_by","hint"?}}` on stdout and exits 0 (item-level miss). Only command-level failures (auth, network) go to stderr with exit 1. `--format json|yaml` collapses results into a `{"data":[…],"@unresolved":[…]}` envelope. ### Debug flag `-d` / `--debug` logs `[debug] METHOD URL` to stderr for every API call on all API commands. Useful for diagnosing auth or routing issues. ## Key Concepts ### Rules - Rules are evaluated **top-to-bottom**; first matching rule wins - Conditions within a rule are **AND-ed** together - Multiple rules act as **OR** (first match wins) - Default (no rule matches) = **fail** for gates, **defaultValue** for configs ### Condition Types 25 built-in types. Most common: - `email` — match by email (operators: any, none, str_contains_any, str_contains_none) - `user_id` — match by user ID - `country` — match by country code - `custom_field` — match any user attribute (use `--field` to specify which) - `public` — matches everyone (used for rollout percentages) - `passes_segment` / `passes_gate` — compose with other entities Default operator is `any` (case-insensitive match). Run `gate criteria` for the full list. ### Dynamic Config Schemas When a config has a JSON Schema, `--return-value` and `defaultValue` updates are validated before the API call. This catches type errors, missing required fields, and unknown fields locally. Set or remove the schema with `config schema set|clear ` (pass a plain JSON object; the CLI handles the API's string encoding). Setting a schema is blocked if existing values don't conform — fix the values first or pass `--force`. Full policy and examples: `agent-statsig config usage`. ### Environments Rules can be scoped to environments (staging, production, etc.) using `--env`. A rule with no environments applies to all environments. ## Project Setup — never paste the Console key The **Console API key is a genuine server secret**. If a user pastes it into chat, **do not** put it into `--console-key`: the value would land in your context window, the command line (argv, shell history, `ps`/`/proc`), transcripts, and any downstream telemetry. The **Client SDK key** (`--client-key`) is *publishable* — it ships in client apps — so it is fine on a flag. Two safe ways to supply the Console key, in order of preference: **1. `--form` — preferred, interactive.** The user runs this in their own terminal; a native OS popup appears for them to type into: ```bash # User runs this — a native dialog (macOS osascript, Linux zenity/kdialog, Windows Win32) appears. agent-statsig project add --form agent-statsig project test ``` The user types the secret straight into the OS; you (the agent) only see a redacted JSON receipt. `--form` prompts for any key not already supplied. If it can't run (SSH/headless), the CLI errors with `fixable_by="human"` and a hint pointing at the stdin fallback — surface it, don't retry. **2. Piped stdin — non-interactive fallback for the Console key.** Keeps the secret off argv/history by reading it from a pipe: ```bash printf '%s' "$CONSOLE_KEY" | agent-statsig project add --client-key ``` The console key comes from stdin; the publishable client key may stay on the flag. Precedence for the console key: `--console-key` flag > piped stdin > `--form`. Tell the user to get their Console API key from Statsig Console → Settings → Keys & Environments.