agent-statsig

Statsig feature flag CLI for AI agents

Language: Go
Version: 0.17.1
License: PolyForm Perimeter 1.0.0
Category: CLI Tool

A Statsig CLI for managing feature gates, dynamic configs, experiments, segments and tags from the command line. Full CRUD and lifecycle, targeting rules addressed by id or name, JSON Schema management for config values validated before they reach the server, and structured output classified so an agent can self-correct.

Features

Five entity types — feature gates, dynamic configs, experiments, segments and tags

Full CRUD plus lifecycle — enable, disable, archive, gate rollout, and experiment start, ship and abandon

Rules addressed the way you think about them — add, update, remove and reorder targeting rules by id or by unique name, with criteria validated

Criteria discovery built in — ask the tool which targeting criteria exist rather than guessing at field names

JSON Schema for dynamic configs — set, inspect or clear a draft 2020-12 schema; the $schema field is added for you

Validation before persistence — return values and defaultValue are checked client-side, and --dry-run gets server-side validation without writing anything

Segment ID management — list, add and remove the ids inside an ID-list segment

The Console key is treated as the secret it is — --form types it into a native OS dialog, or pipe it on stdin; the publishable client SDK key may stay on a flag

Structured output — JSON, YAML or NDJSON, with errors classified fixable_by: agent|human|retry

Progressive documentation — top-level overview, then per-entity reference, then criteria discovery

Multi-project via aliases, credentials keychain-first

Zero runtime dependencies — a single compiled Go binary

Install

Homebrew

$ brew install shhac/tap/agent-statsig

AI Agent Skill

$ npx skills add shhac/agent-skills --skill agent-statsig --global

GitHub Release (macOS)

$ curl -L https://github.com/shhac/agent-statsig/releases/latest/download/agent-statsig-darwin-arm64.tar.gz | tar xz

Go Install

$ go install github.com/shhac/agent-statsig/cmd/agent-statsig@latest

Build from Source

$ git clone https://github.com/shhac/agent-statsig.git && cd agent-statsig && make build

Getting Started

Statsig gives you two kinds of key and they need different handling. The Console API key is a genuine server secret and must stay off argv, shell history and any agent transcript; the Client SDK key is publishable and is fine on a flag. Both come from Statsig Console → Settings → Keys & Environments.

01 · Add a project without the secret on the command line

$ agent-statsig project add myproject --form

--form prompts for whichever keys are missing through a native OS dialog, so the Console key is typed straight into the OS.

02 · Or pipe it, for CI

$ printf '%s' "$CONSOLE_KEY" | agent-statsig project add myproject --client-key "client-xxx"

Console key precedence is --console-key, then piped stdin, then --form. The publishable client key can stay on the flag.

03 · Test connectivity

$ agent-statsig project test

The client key is what gate check needs for evaluation; the Console key is what everything else needs.

04 · Find out what you can target on

$ agent-statsig rule criteria

Criteria discovery, so a rule is written against fields that exist. agent-statsig usage gives the overview; each entity has its own reference.

Usage

>_ List feature gates

$ agent-statsig gate list

>_ Evaluate a gate for a user

$ agent-statsig gate check my_feature --user '{"userID":"user123"}'

>_ Create a gate

$ agent-statsig gate create new_feature --description "Enable new checkout flow"

>_ Add a targeting rule

$ agent-statsig gate rule add new_feature --name "Beta users" --criteria user_id --value user1 --value user2

>_ Reorder rules by name

$ agent-statsig gate rule move new_feature "Beta users" --to 0

>_ Roll a gate out by percentage

$ agent-statsig gate rollout new_feature --pass-percentage 25

>_ Validate a config value without saving it

$ agent-statsig config value set pricing_tiers '{"pro":29}' --dry-run

>_ Ship an experiment

$ agent-statsig experiment ship checkout_test