Agent workflows

The CLI is designed to be discoverable by an agent without relying on a stale prompt or parsing decorative terminal output.

The default loop

superflag contract --json
superflag doctor --json
superflag flags list --app my-app --env staging --json

Then choose the smallest safe workflow:

inspect current state;
validate the desired document offline;
calculate a diff or impact report;
produce an integrity-checked plan;
run the plan with --dry-run;
apply the same plan with a version precondition; and
read state or the change journal to verify the result.

superflag export --app my-app --env staging --out current.superflag.json
cp current.superflag.json desired.superflag.json
# Edit only the intended values in desired.superflag.json.
superflag validate --file desired.superflag.json --json
superflag diff --file desired.superflag.json --app my-app --env staging --json
superflag plan --file desired.superflag.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 get <changed-flag> --app my-app --env staging --json
superflag changes list --app my-app --env staging --source agent --json
# Use the returned id for an exact lookup:
superflag changes list --app my-app --id <change-id> --json

The plan binds immutable target identity and the exact current config version; do not copy a version number from an example. Apply uses that atomic compare-and-swap precondition and a plan-derived idempotency key. Dry-run never sends a mutation. Verify the changed resource directly; when a workflow plan records source: "agent", its stable change ID can also be inspected through the change journal.

Stable JSON

Successful commands emit one document to stdout:

{
  "ok": true,
  "data": {},
  "meta": { "requestId": "request-id", "configVersion": 42 }
}

Failures emit one document to stderr with stable codes and remediation; stdout remains empty:

{
  "ok": false,
  "error": {
    "code": "conflict",
    "message": "The configuration changed",
    "retryable": false,
    "remediation": "Re-export and create a new plan"
  },
  "meta": { "requestId": "request-id" }
}

Agents must check both the envelope and process exit status. Success is 0; usage/validation is 2; authentication 3; forbidden 4; not found 5; conflict/precondition 6; network/timeout/rate limit 7; unsupported capability or not-ready/stale result 8; and invalid experiment analysis 9. Exit 1 is reserved for an internal failure or an unhealthy completed doctor result.

Ask feature and experiment questions directly

Use the bounded read contract instead of scraping the dashboard or rebuilding statistics from event rows:

superflag insights flag checkout --from -24h --app my-app --env prod --json
superflag experiments results checkout-copy --app my-app --env prod --json
superflag experiments health checkout-copy --app my-app --env prod --json
superflag exposures query --key checkout --from -24h \
  --app my-app --env prod --json

Preserve schema/engine versions, freshness, query cost, readiness, and health reason codes in downstream decisions. A structured success response is not a winner claim. Stream large redacted reads with exposures export, persist its typed checkpoint records, and resume with the latest non-null cursor.

Keep evaluation context out of arguments

Read-only inspection uses a context file or stdin and requires an explicit instant:

superflag inspect explain checkout \
  --context-file context.json \
  --fallback false \
  --at 2030-01-15T12:00:00Z \
  --app my-app \
  --env prod \
  --json

Inline context is intentionally unsupported so identifiers do not enter shell history or process arguments. Inspection does not emit a feature exposure.

printf '%s' '{"targetingKey":"user-123","attributes":{"plan":"pro"}}' | superflag inspect segment beta --context-file - --at 2030-01-15T12:00:00Z --app my-app --env prod --json
superflag inspect dependencies flag:checkout --app my-app --env prod --json
superflag inspect impacts segment:beta --app my-app --env prod --json
superflag inspect simulate --file current.superflag.json --proposed desired.superflag.json --scenarios scenarios.json --app my-app --env prod --json

Pass --file exported.superflag.json to run the same evaluator offline.

One-time secrets

Key and app creation reveal plaintext secrets only with explicit --show-secrets. Supply a stable idempotency key so an interrupted response can recover the same secret during the delivery window:

superflag keys create \
  --app my-app \
  --env prod \
  --type sdk \
  --show-secrets \
  --idempotency-key rotate-prod-20300115 \
  --json

Do not place returned secrets in the agent transcript. Send them directly to a secret manager or a secure user-owned file.

Install the Superflag skill

The CLI package includes a portable skill matched to that exact package version. Install it into the standard workspace location, verify it in CI, and update it only after intentionally changing the pinned CLI version:

superflag skill install
superflag skill check
superflag skill update

The default destination is .agents/skills/superflag/; pass --target <directory> for a different canonical location. The CLI records its package version, public source URL, and content digest in .superflag-skill.json. check is entirely local and exits with conflict code 6 when the vendored files drift from the installed package. JSON formatting is ignored for the provenance manifest, but its exact fields and values must match. install refuses to overwrite different existing instructions; review them and use update for an explicit staged replacement with rollback on failure. The public skill contains only installed-CLI guidance. Repository-specific paths, development commands, and allowed app/environment scope belong in the consuming repository’s own agent guidance. superflag contract --json remains the installed version’s source of truth for command arguments, capabilities, and exits. The same skill source is visible in the CLI repository.

Start here

Node and server SDK

React SDK

React Native and Expo

Core SDK

CLI and agents

Feature decisions

HTTP API

Agent workflows

Agent workflows

The default loop

Stable JSON

Ask feature and experiment questions directly

Keep evaluation context out of arguments

One-time secrets

Install the Superflag skill

​Agent workflows

​The default loop

​Stable JSON

​Ask feature and experiment questions directly

​Keep evaluation context out of arguments

​One-time secrets

​Install the Superflag skill

Agent workflows

The default loop

Stable JSON

Ask feature and experiment questions directly

Keep evaluation context out of arguments

One-time secrets

Install the Superflag skill