> ## Documentation Index
> Fetch the complete documentation index at: https://superflag.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent workflows

> Use Superflag safely and deterministically from coding agents and automation

# 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

```bash theme={null}
superflag contract --json
superflag doctor --json
superflag flags list --app my-app --env staging --json
```

Then choose the smallest safe workflow:

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

```bash theme={null}
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:

```json theme={null}
{
  "ok": true,
  "data": {},
  "meta": { "requestId": "request-id", "configVersion": 42 }
}
```

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

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](https://github.com/superflag-sh/cli/tree/main/skills/superflag).