CLI command reference

Run superflag --help for human help. Run superflag contract --json or superflag --help --json for the complete versioned machine contract bundled with your installed CLI.

Quick commands

superflag use <app> <env>
superflag get <flag> --json
superflag set <flag> <value> --json
superflag config --json
superflag status --json

Agent skill lifecycle

superflag skill install
superflag skill check
superflag skill update
superflag skill install --target path/to/skills/superflag

The default target is .agents/skills/superflag/. install refuses to replace a different existing directory, update performs an explicit staged replacement, and network-free check exits with conflict code 6 on content, provenance, or package-version drift. Skill instructions are byte-exact; provenance JSON may be reformatted, but its exact fields and values must match.

Direct management

superflag apps list --json
superflag envs list --app my-app --json
superflag flags list --app my-app --env prod --json
superflag flags upsert --app my-app --env prod --key checkout --type bool --value true --client --json
superflag flags toggle --app my-app --env prod --key checkout --json
superflag flags rollout --app my-app --env prod --key checkout --percentage 25 --json
superflag flags variants --app my-app --env prod --key theme --variant "classic:50:control" --variant "modern:50:treatment" --json

--client makes a legacy flag client-deliverable; --no-client explicitly makes it server-only. Variant weights must total 100.

Declarative configuration

superflag export --app my-app --env staging --out staging.superflag.json
superflag validate --file staging.superflag.json --json
superflag diff --file desired.json --app my-app --env staging --json
superflag plan --file desired.json --app my-app --env staging --source agent --reason "describe the intended change" --out plan.json
superflag apply --plan plan.json --dry-run --json
superflag apply --plan plan.json --json
superflag promote --app my-app --from staging --to prod --dry-run --json
superflag codegen --file desired.json --out superflag.generated.ts

Compatible existing-value and advanced structural changes use one atomic bulk request. The plan’s config version is the CAS precondition; never copy a literal version from an example. Source and reason are integrity-bound in the plan and cannot be overridden during apply. Unsupported changes fail before mutation.

History and rollback

superflag versions list --app my-app --env prod --json
superflag versions get 42 --app my-app --env prod --json
superflag versions diff 41 42 --app my-app --env prod --json
superflag rollback 41 --dry-run --app my-app --env prod --out rollback-plan.json --json
superflag rollback apply --plan rollback-plan.json --dry-run --json
superflag rollback apply --plan rollback-plan.json --json
superflag rollback recover --plan rollback-plan.json --json

History is composite configuration plus experiment state. Rollback plans bind the exact experiment version vector so an old config cannot be silently joined with current experiments.

Metrics

superflag metrics list --app my-app --env prod --json
superflag metrics get <metric-id> --app my-app --env prod --json
superflag metrics explain <metric-id> --app my-app --env prod --json
superflag metrics create --key checkout-conversion --file metric.json --app my-app --env prod --dry-run --json
superflag metrics revise <metric-id> --file metric-v2.json --if-revision 1 --app my-app --env prod --json
superflag metrics validate --file metric-operation.json --json
superflag metrics plan --file metric-operation.json --out metric-plan.json --json
superflag metrics apply --plan metric-plan.json --dry-run --json
superflag metrics apply --plan metric-plan.json --json

Metric definitions are immutable revisions and support conversion, count, sum, mean, and derived ratio kinds.

Experiments

superflag experiments list --app my-app --env prod --json
superflag experiments create --file experiment.json --app my-app --env prod --idempotency-key checkout-copy-v1 --json
superflag experiments start <id> --if-version 1 --idempotency-key checkout-start --json
superflag experiments pause <id> --if-version 2 --idempotency-key checkout-pause --json
superflag experiments ramp <id> --allocation control=25000,treatment=75000 --if-version 3 --idempotency-key checkout-ramp --dry-run --json
superflag experiments complete <id> --if-version 4 --idempotency-key checkout-complete --json
superflag experiments results <id-or-key> --app my-app --env prod --json
superflag experiments health <id-or-key> --app my-app --env prod --json
superflag experiments run <id-or-key> --run-id <run-id> --app my-app --env prod --json

Declarative experiments validate|plan|apply|recover commands bind the full definition, current config and experiment versions, and immutable target identity. Lifecycle mutations require CAS and caller-stable idempotency. Result and health commands return the server’s effect intervals, sufficient statistics, readiness, health reasons, freshness, and engine version. They do not infer a winner. A collecting or stale result exits 8; invalid analysis exits 9. Recompute is an explicit mutation:

superflag experiments recompute <id-or-key> --confirm \
  --idempotency-key experiment-recompute-20300115 \
  --app my-app --env prod --json

Confirmation cannot bypass a raw-input gap or source-watermark conflict.

Feature insights and exposures

superflag insights flag checkout --from -24h --app my-app --env prod --json
superflag insights query --measure exposures --measure approximateUniqueSubjects \
  --dimension variation --filter platform=ios --from -24h \
  --app my-app --env prod --json
superflag exposures query --key checkout --from -24h \
  --app my-app --env prod --json
superflag exposures export --key checkout --from -24h \
  --app my-app --env prod > exposures.ndjson

Queries use only allow-listed feature dimensions and measures. Aggregate ranges are at most 90 days; event pages are at most 100 rows across seven days. exposures export streams typed event and checkpoint NDJSON records. Save the latest non-null cursor and resume with --cursor; do not add --json to an NDJSON export.

Inspection and journal

superflag inspect explain checkout --context-file context.json --fallback false --at 2030-01-15T12:00:00Z --app my-app --env prod --json
superflag inspect dependencies flag:checkout --app my-app --env prod --json
superflag changes list --app my-app --env prod --source agent --limit 100 --json
superflag changes list --app my-app --id <change-id> --json

The change journal returns redacted structured changes, safe authority metadata, and before/after versions. Raw credentials and request payloads are excluded.

Start here

Node and server SDK

React SDK

React Native and Expo

Core SDK

CLI and agents

Feature decisions

HTTP API

Command reference

CLI command reference

Quick commands

Agent skill lifecycle

Direct management

Declarative configuration

History and rollback

Metrics

Experiments

Feature insights and exposures

Inspection and journal

​CLI command reference

​Quick commands

​Agent skill lifecycle

​Direct management

​Declarative configuration

​History and rollback

​Metrics

​Experiments

​Feature insights and exposures

​Inspection and journal

CLI command reference

Quick commands

Agent skill lifecycle

Direct management

Declarative configuration

History and rollback

Metrics

Experiments

Feature insights and exposures

Inspection and journal