flitz status

The onboarding and troubleshooting entry point: every check, what each verdict means, and the command each hint points at.

flitz status is the one command to run to find out whether this machine and this project are ready, and the first thing to run when something else fails. It is purely informational: it changes nothing and always exits 0. The verdict lives in the markers, not in the exit status, so a flitz status step in CI is a report, never a gate. Scripts that want the verdicts use --json.

cd /path/to/your/flutter/app
flitz status

Flitz 1.4.0 on linux-x64

Checking your setup…

  ✓ your organization's Flitz license is active

  ✓ project pinned to <tag>
      ✓ SDK <tag> is in the cache
      ✓ SDK <tag> is the latest release

  ⚠ no loader-plugin credentials are stored
    → run `flitz plugins credentials --write`
  ✓ loader plugin <version> supports <tag>

  ✓ CLI 1.4.0 is current

The header prints before the checks run: the network rows take a few seconds, and the header is what tells you the pause is work rather than a hang. Checks are grouped — account, project, loader plugins, CLI — with a blank line between groups. A check that is a statement about another one is indented under it: "SDK … is in the cache" is a fact about the pin above it.

There is no closing tally. The markers already carry the verdict.

Verdicts

Marker	Verdict	Meaning
`✓`	ok	Fine; nothing to do.
`⚠`	advisory	Works today, but worth knowing: a deliberate older pin, absent plugin credentials, a newer CLI. Never blocks.
`✗`	blocking	Something you need will not work until you act on the hint.
`?`	unknown	Could not be determined: the service could not be reached, or there is no credential to ask with.

Every non-✓ row carries at least one → hint naming the command that resolves it. In plain output (CI, --no-color) the markers render as [ok], [warn], [fail], and [unknown].

Checks

Nine checks run. The five local ones always run and never touch the network, so status says something useful on a machine with no connectivity and no credential. The four network ones degrade quietly to ? when the service is out of reach — nothing else changes, and there is no --offline flag because there is nothing to opt into.

The id column is the stable identifier the --json document keys on; the human message may be reworded, the identifier will not.

Account

id	Check	Verdicts and hints
`credential`	A credential is available — a stored sign-in or `FLITZ_APIKEY`.	`✗ you are not logged in to Flitz` → `flitz login`, or set `FLITZ_APIKEY` for CI. Not shown when one is present: which kind you hold is not a finding; whether it works is what the license row answers.
`license`	Your organization's license is active. (network)	`✓` active · `✗ your organization's Flitz license is not active` → contact your organization administrator · `?` unreachable, or no credential to ask with.

Project

id	Check	Verdicts and hints
`project_pin`	`flitz.yaml` exists in the current directory, parses, and names a well-formed release tag.	`✓ project pinned to <tag>` · `✗ no SDK is pinned for this project` or `✗ flitz.yaml names no well-formed release tag` → `flitz sdk use latest`.
`sdk_installed`	The pinned SDK is in the cache. (under the pin)	`✓ SDK <tag> is in the cache` · `✗ SDK <tag> is not in the cache` → `flitz sdk use <tag>`.
`sdk_complete`	The cached tree looks complete: the SDK marker is present and matches this host, and the key build tools exist. A light check — it does not re-hash the archive. (under the cache row)	Shown only when it does not pass. `⚠ SDK <tag> is missing a build tool` → `flitz sdk install --force <tag>` (verified but damaged) · `✗ SDK <tag> has no marker for <host>` → `flitz sdk use <tag>`.
`sdk_latest`	The pinned tag is the latest release. (network, under the pin)	`✓ SDK <tag> is the latest release` · `⚠ SDK <latest> is the latest release; this project pins <tag>` → `flitz sdk use latest` if the pin is not deliberate — staying behind is a legitimate choice · `?` unreachable.

Loader plugins

id	Check	Verdicts and hints
`plugin_credentials`	Loader-plugin repository credentials are stored in `~/.gradle/gradle.properties` and `~/.netrc`.	`✓ loader-plugin credentials are stored` · `⚠ no loader-plugin credentials are stored` → `flitz plugins credentials --write` · `?` the stores could not be read. The CLI checks only its own stores — it never reads your project's build files, so it cannot tell you whether the plugins are wired into the app.
`plugin_version`	A loader-plugin version resolves for the pinned tag. (network)	`✓ loader plugin <version> supports <tag>` · `⚠ no loader plugin version supports <tag>; the lowest published floor is <tag>` → `flitz plugins configure` for the details · `?` unreachable.

CLI

id	Check	Verdicts and hints
`cli_version`	A newer CLI is published. (network, anonymous — runs even with no credential)	`✓ CLI <version> is current` · `⚠ CLI <newer> is available (you have <version>)` → re-run the install script · `?` unreachable.

The build host is deliberately not a check: the CLI is distributed as per-host binaries for exactly the supported hosts, so it could never fail on a machine able to run it. --json reports the host as a field regardless.

Rows hidden without `-v`

Two kinds of row are omitted unless you pass -v, because printing them buries the one row that matters:

a check whose prerequisite did not hold, so it never ran — with no pin, four further checks have nothing to look at; and
a check worth a line only when it does not pass (credential, sdk_complete).

flitz status -v prints every row, skipped ones as ?. --json always includes every check, with skipped set where it applies.

Drift is reported here, and only here

A newer CLI earns an ambient nudge after other commands (Configuration → Update notices). A newer SDK tag or plugin version never does: a project pins deliberately, and moving the pin is a decision. status is where you check both, and it is the only command that fetches the version feed unthrottled — an explicit health request should not report stale facts.

JSON output

flitz status --json

{
  "cli_version": "1.4.0",
  "host": "linux-x64",
  "checks": [
    {
      "id": "sdk_installed",
      "verdict": "blocking",
      "message": "SDK <tag> is not in the cache",
      "hints": ["run `flitz sdk use <tag>`"],
      "group": "project",
      "depends_on": "project_pin",
      "skipped": false
    }
  ],
  "blocking": 1,
  "advisory": 0
}

verdict is one of ok, advisory, blocking, unknown. Every check appears, including the ones the human report hides; key on id and filter for yourself:

flitz status --json | jq -r '.checks[] | select(.verdict=="blocking") | .message'

The exit status is still 0 whatever the verdicts say. The document contains no credential, token, or identity — only whether a credential works.

On this page