Configuration

config.yaml, the environment variables the CLI honors, how they combine with flags, and the update notice.

The CLI works with no configuration at all — an absent config.yaml is the common case. What follows is the complete list of knobs, where the CLI keeps its state, and how the sources combine.

config.yaml

Persistent preferences live in a per-user file outside any project:

~/.config/flitz/config.yaml        (or $XDG_CONFIG_HOME/flitz/config.yaml)

You author it; the CLI only reads it. It is a YAML mapping with three recognized keys:

~/.config/flitz/config.yaml

color: auto          # auto | always | never
update_check: true   # false suppresses the ambient update notice
assume_yes: false    # true answers every confirmation prompt affirmatively

Key	Values	Default	Effect
`color`	`auto` / `always` / `never`	`auto`	Rich or plain output. `auto` means rich on a terminal, plain otherwise. See Rich and plain output.
`update_check`	`true` / `false`	`true`	`false` suppresses the update notice.
`assume_yes`	`true` / `false`	`false`	`true` behaves as though `--yes` were passed to every command — including the default-no `apikey revoke` prompt.

Unknown keys are ignored, so the schema can grow. A file that is unreadable, not a YAML mapping, or holds a value of the wrong type produces one warning naming the file and the offending key, and the command proceeds with defaults for the affected settings. A broken preference file never blocks work.

The file holds no secrets. Your sign-in credential lives in credentials.json; the organization API key is environment-only. Neither is ever written here.

Environment variables

Variable	Effect
`FLITZ_APIKEY`	The organization API key. When set and non-empty, the whole CLI authenticates with it and never reads the stored sign-in; the update notice is suppressed; the `apikey` mutations are refused. See flitz apikey.
`FLITZ_NO_UPDATE_CHECK`	Any non-empty value suppresses the update notice.
`NO_COLOR`	Non-empty forces plain output. Beats `FORCE_COLOR`.
`FORCE_COLOR`	Non-empty forces rich output even when the stream is not a terminal.
`TERM`	Unset or `dumb` yields plain output when nothing above decided.
`XDG_CONFIG_HOME`	Where `flitz/config.yaml` and `flitz/credentials.json` live. Default `~/.config`.
`XDG_CACHE_HOME`	Where `flitz/sdk/` and `flitz/update-check.json` live. Default `~/.cache`.
`XDG_BIN_HOME`	Where the install script places the `flitz` binary. Default `~/.local/bin`.
`HOME`	The fallback for all of the above.

Home resolution is explicit. For each root the CLI uses the XDG_ variable when it is set and absolute, else $HOME when it is set and absolute, else it aborts with a general error (exit 2) naming which variable it needs. It never silently creates .config/ or .cache/ trees inside your working directory.

FLUTTER_ROOT is not read by the public CLI: flitz publish resolves the SDK from the pin and the cache by itself. Setting it for your own tools is fine — see sdk path.

Precedence

command-line flag  →  environment variable  →  config.yaml  →  built-in default

Concretely, for output mode: --no-color beats NO_COLOR, which beats FORCE_COLOR, which beats color: in config.yaml, which beats terminal detection. For prompts: --yes and assume_yes: true are equivalent. For the update notice: --json, FLITZ_APIKEY, FLITZ_NO_UPDATE_CHECK, and update_check: false each suppress it independently.

Filesystem locations

Path	Contents	Written by
`$XDG_CONFIG_HOME/flitz/config.yaml`	Preferences (above).	You.
`$XDG_CONFIG_HOME/flitz/credentials.json`	Your sign-in credential, mode `0600`.	`flitz login`; removed by `flitz logout`.
`$XDG_CACHE_HOME/flitz/sdk/<tag>/`	One cached SDK per release tag, plus internal staging and lock directories.	`flitz sdk install` / `use`; removed by `flitz sdk remove`.
`$XDG_CACHE_HOME/flitz/update-check.json`	When the update feed was last fetched and when you were last warned.	The update notice and `flitz status`.
`<project>/flitz.yaml`	The project's SDK pin. Committed.	`flitz sdk use`.
`~/.gradle/gradle.properties`, `~/.netrc`	The loader-plugin repository token.	`flitz plugins credentials --write`.
The path you name with `publish --qr-output`	A PNG of the deeplink QR.	`flitz publish`.

Nothing else is written. There is no persistent log file and no rotating diagnostic output; diagnostics are produced on demand by -v and by the bug-report capture.

Update notices

When a newer flitz is published, the CLI mentions it — ambiently, quietly, and rarely:

⚠ flitz 1.5.0 is available; you have 1.4.0
  → re-run the install script from https://download.flitz.dev

The check runs after your command has finished, so it can neither delay a command nor fail one, and it fetches the public release feed anonymously with a two-second deadline and no retry. Any failure — offline, DNS, a slow network — is silent. The warning appears at most once per 24 hours and never changes the exit code.

It stays quiet when any of these hold:

stderr is not a terminal (nobody is watching);
FLITZ_APIKEY is set (a machine identity is not a person to nag);
FLITZ_NO_UPDATE_CHECK is set to anything non-empty;
config.yaml sets update_check: false;
--json was passed (nothing may perturb a machine-readable stream);
the feed was fetched less than 24 hours ago.

To silence it permanently:

export FLITZ_NO_UPDATE_CHECK=1        # in your shell profile

or update_check: false in config.yaml.

Pinned-SDK and plugin drift are never nagged about. A project that pins an older SDK tag has made a legitimate, deliberate choice; the same holds for the loader-plugin version. Both are reported only when you ask, in flitz status, which is also the only command that fetches the update feed unthrottled.

config.yaml

Environment variables

Precedence

Filesystem locations

Update notices

On this page