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 informational: it changes nothing in your project or SDK cache 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 <version> 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 <plugin-version> supports <tag>

  ✓ CLI <version> 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, there is no credential to ask with, or the service rejects your stored sign-in (it has ended or was revoked).

Every ⚠ and ✗ row carries at least one → hint saying what to do next — usually the command that fixes it. ? rows carry none: re-run flitz status once you are online or signed in. In plain output (CI, --no-color) the markers render as [ok], [warn], [fail], and [unknown].

“unknown (offline)” while you are online

A sign-in that has ended, or that the service rejects, also reports as ? license — unknown (offline), and the other network rows follow suit. When you know you are online, run any licensed command — flitz sdk releases is a harmless one — to see the real cause, or run flitz login again.

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` → ask your organization's Owner to open Billing in the portal · `?` unreachable, no credential to ask with, or a stored sign-in the service rejects.

An inactive license is restored by your organization's Owner, from the Billing page of the Flitz portal. Links you already published keep working meanwhile.

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 `✗ <path>/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 SDK looks complete. A quick check: it does not re-verify the download. (under the cache row)	Shown only when it does not pass. `⚠ SDK <tag> is missing a build tool` → `flitz sdk install --force <tag>` · `✗ 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. It checks only that a token is present, not that it is current, and 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 supports the pinned tag. (network)	`✓ loader plugin <plugin-version> supports <tag>` · `⚠ no loader plugin version supports <tag>; the lowest published floor is iteration <n>` or `⚠ no loader plugin version is published yet` → `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 from `https://download.flitz.dev` · `?` unreachable.

--json also reports the host the CLI runs on, as a field.

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 always asks for the current answer when it runs.

JSON output

flitz status --json

{
  "cli_version": "<version>",
  "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