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 <name> (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 <name> 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

# Explore (safe, read-only)
agent-statsig gate list [--search <text>] [--tag <tag>]
agent-statsig gate get <name>...                 # 1..N ids, NDJSON default; @unresolved for misses
agent-statsig config get <name>...
agent-statsig experiment get <name>...
agent-statsig segment get <name>...

# Modify gates
agent-statsig gate enable <name>
agent-statsig gate disable <name>
agent-statsig gate rollout <name> --percent 50
agent-statsig gate rule add <name> --name "Rule" --criteria email --value user@co.com
agent-statsig gate rule update <name> --rule <id-or-name> --add-value new@co.com
agent-statsig gate rule remove <name> --rule <id-or-name>
agent-statsig gate rule move <name> --rule <id-or-name> --position <n|top|bottom>   # 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> --name "Rule" --criteria email --value user@co.com --return-value '{"key":"val"}'
agent-statsig config schema get <name>
agent-statsig config schema set <name> '{"type":"object","required":["key"]}'
agent-statsig config value set <name> '{"key":"val"}'   # defaultValue (no-rule fallback)

# Experiment lifecycle
agent-statsig experiment start <name>
agent-statsig experiment ship <name> --group <id> --reason "text"
agent-statsig experiment abandon <name> --reason "text"

# Segment IDs
agent-statsig segment ids add <name> --id user1 --id user2
agent-statsig segment ids remove <name> --id user1

# Manage tags
agent-statsig tag list
agent-statsig tag create <name> [--description <text>] [--is-core]
agent-statsig tag get <id>
agent-statsig tag update <id> [--name <name>] [--description <text>] [--is-core]
agent-statsig tag delete <id>

# Apply tags when creating/updating entities
agent-statsig gate create <name> --tag <tag-name>
agent-statsig config create <name> --tag <tag-name>
agent-statsig experiment create <name> --tag <tag-name>
agent-statsig gate update <name> '{}' --tag <tag-name>

Detailed Reference

For full command details with examples, run per-entity usage:

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 <id>... 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 <name> (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:

# User runs this — a native dialog (macOS osascript, Linux zenity/kdialog, Windows Win32) appears.
agent-statsig project add <alias> --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:

printf '%s' "$CONSOLE_KEY" | agent-statsig project add <alias> --client-key <clientkey>

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.