Configuration

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:

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

Unknown keys are ignored, so the schema can grow. A file that is unreadable, not valid YAML, not a YAML mapping, or holds a value of the wrong type produces one plain line on stderr, on every command, naming the file and the problem:

warning: ignoring preferences in /home/you/.config/flitz/config.yaml — `assume_yes` must be true or false

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.

flitz.yaml

Each project also has a committed flitz.yaml. flitz sdk use writes its sdk: line; the other three keys are optional and yours to add:

sdk: <flutter-version>+flz.<N>   # the SDK pin, written by flitz sdk use
app: acme                        # app key; default: the pubspec name
track: demo                      # a fixed track; default: the current Git branch
schema: acme                     # deeplink scheme; default: flitz

The CLI reads flitz.yaml from the directory you run it in, also when you pass publish --dir. It rewrites only sdk:, keeping your other keys and comments. A file that is not valid YAML, is not a mapping, or gives one of these keys a non-string value fails the command with a usage error (exit 1) naming the file.

Environment variables

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. For the publish values app, track, and schema: the flag (--app, --track, --schema), then flitz.yaml, then the default (the pubspec name, the Git branch, flitz).

Filesystem locations

Beyond these, flitz publish works in a scratch directory under $TMPDIR that it deletes when it finishes, along with the temporary .flitz it uploads, and its build writes into your app the way any Flutter build does (build/, .dart_tool/, and possibly pubspec.lock and the pub cache). 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 <newer-version> is available; you have <version>
  → 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.