flitz apikey

Create, rotate, revoke, and inspect the organization's single CI API key, and run the CLI non-interactively with FLITZ_APIKEY.

CI has no browser to sign in with. Instead, your organization has one long-lived API key that pipelines present through the FLITZ_APIKEY environment variable. The apikey group manages that key.

Command	What it does
`flitz apikey create`	Mint the key. Prints the plaintext once. Fails if one already exists.
`flitz apikey rotate`	Replace the key, invalidating the previous one. Prints the new plaintext once.
`flitz apikey revoke`	Delete the key. Confirms first; every pipeline loses access immediately.
`flitz apikey status`	Show whether a key exists, obfuscated. Never the plaintext.

All four need an active license. create, rotate, and revoke additionally require an interactive session — a developer who ran flitz login. Run under FLITZ_APIKEY, they refuse locally, before any network call, with Flitz key management requires an interactive session (exit 3). A pipeline cannot mint, rotate, or revoke its own credential. status is a read and works under any credential.

One key per organization

The key is shared by every pipeline in the organization. Rotating or revoking it cuts off all of them at once, and each must be updated with the new value. That is the deliberate cost of a single durable key.

create

flitz apikey create

Created organization API key:

  <key>

Store it as the FLITZ_APIKEY secret in your CI system — it will not be shown again.

The plaintext is available only in this output. If it is lost, rotate to mint a new one. If a key already exists, create reports that one exists, points at flitz apikey rotate and flitz apikey status, and exits 1.

rotate

flitz apikey rotate

Mints a new key, invalidates the old one, prints the new plaintext once, and reminds you that every pipeline using the old key must be updated. If no key exists yet, it behaves like create.

revoke

flitz apikey revoke

Revoke the organization API key? Every pipeline using it loses access immediately. [y/N]

The prompt defaults to no. On yes, the key is deleted and every pipeline using it loses access immediately. Revoking is idempotent — it succeeds when no key exists.

Non-interactively — no terminal to ask on — revoke fails with a usage error (exit 1) unless you pass --yes:

flitz apikey revoke --yes

Deactivating the organization's license denies the key (and every developer) without touching the key itself.

status

flitz apikey status

Organization API key:
  Value:     ****…abcd
  Created:   2026-…
  Last used: 2026-…

or No organization API key. Run 'flitz apikey create' to mint one.

With --json:

{ "present": true, "name": "…", "obfuscated_value": "****…abcd", "created_at": "…", "last_used_at": "…" }

Fields the service does not know are absent. No --json document ever carries a plaintext key.

Using `FLITZ_APIKEY` in CI

Once, from an interactive session, mint the key and store the printed value in your CI system's secret store. Expose it to jobs as an environment variable:

export FLITZ_APIKEY=<organization-api-key>

When FLITZ_APIKEY is set and non-empty, the whole CLI authenticates with it: it is the single credential presented to every licensed action — SDK download, publish, and the plugins group — and the stored sign-in, if any, is never read. flitz login is skipped entirely.

The CLI treats the variable as a secret: it is never echoed, it is redacted in every diagnostic and in the bug-report capture, and it is never written to disk.

A CI job is one command

On a checkout that carries only the committed flitz.yaml:

export FLITZ_APIKEY="$FLITZ_APIKEY_SECRET"
flitz publish --yes --json

--yes lets publish download the pinned SDK unattended when the cache is cold. Without it, a non-interactive publish with no cached SDK fails fast with a usage error rather than starting a large transfer by surprise — see On-demand SDK download.
--json gives the job a parseable result on stdout and nothing else.

Where the cache is warmed separately — a cached CI volume, a container image — warm it with flitz sdk use (no argument, reading the committed pin) and then run a plain flitz publish.

A CI job is a first-class non-interactive caller: output is plain (no color, glyphs, or spinners, because stderr is not a terminal), the ambient update notice never runs, no prompt is displayed, and any prompt that would have been asked fails fast naming the flag that answers it.

What works under a key

Works	Refused
`flitz sdk install` / `use` / `releases`, `flitz publish`, `flitz plugins configure` / `credentials` / `skill`, `flitz apikey status`, `flitz status`	`flitz apikey create` / `rotate` / `revoke` (exit 3, "requires an interactive session")

Readiness in a script is flitz status --json; the result of a publish is flitz publish --json; and the exit code, never the prose, says what class of thing went wrong — see Exit codes.