flitz sdk

The Flitz SDK is a complete Flutter SDK with the Flitz engine and the compiler that turns your app into a bundle. It is not downloaded by hand: the flitz CLI is the only thing that fetches and places it, into a CLI-managed cache at ~/.cache/flitz/sdk/<tag>/, one directory per release tag.

A release tag has the shape <flutter-version>+flz.<N>: the upstream Flutter version, then <N>, the Flitz iteration. The iteration increases with each Flitz release and is shared across Flutter versions, so a Flutter version's first tag need not be flz.1. flitz sdk releases lists what is published; latest resolves to the highest tag, newest Flutter version first. Copy tags from flitz sdk releases rather than typing them — the service looks a tag up exactly as written.

releases, install, and use need the network, a credential, and an active license — every time, including for a tag that is already cached. list, path, and remove need no credential and work offline.

To choose a tag when no release matches your app's Flutter version, see Getting started.

Requirements

Installing an SDK needs the system tar with xz support — slim CI images may need the xz-utils package — and room in the cache: each tag is several hundred megabytes to download and more than a gigabyte on disk. sdk use names the download size before it starts.

releases

flitz sdk releases

Available Flitz releases:
  <tag>  (installed, pinned)
  <tag>  (installed)
  <tag>

With --json: { "releases": [ { "tag", "installed", "pinned" } ] }.

install

flitz sdk install latest       # or an explicit <tag>
flitz sdk install              # the tag this project pins
flitz sdk install --force <tag>

Downloads the SDK for your host into the cache without touching the project pin. With no argument it installs the tag the project pins; an unpinned project with no argument is a usage error (no tag was named and this project pins none) rather than a silent guess at latest.

Already cached? After confirming the tag with the Flitz service, it says SDK <tag> already cached. and stops. --force re-downloads and replaces the cached tree, which is how you repair an entry that flitz status reports as missing a build tool.

install was asked for the download outright, so it never prompts.

use and flitz.yaml

cd /path/to/your/flutter/app
flitz sdk use latest           # or: flitz sdk use <tag>

sdk use asks the Flitz service to resolve the tag — latest becomes a concrete tag, and that concrete tag is what gets pinned — then:

1. Pins the tag by writing flitz.yaml at the project root — the current directory:

   sdk: <tag>

2. Stops if that tag is already cached (SDK <tag> already cached.). Otherwise it offers the download with a default-yes prompt naming the tag and its approximate size. Accept, and the archive streams into the cache, is verified against its SHA-256, and is moved into place only once it verifies. Decline, and the pin is still written:

   Not downloaded. Run `flitz sdk install` when you are ready.

The pin is written before the download on purpose, so a declined, interrupted, or failed transfer still leaves the project pinned to the tag you chose and only the bytes outstanding. Non-interactively (no terminal to ask on), sdk use downloads without asking — a cold CI cache is exactly what it is run to warm.

Commit flitz.yaml. A fresh checkout on another machine reproduces the exact same SDK with an argument-less flitz sdk use, or with a single flitz publish --yes. The file may also set app:, track:, and schema: for flitz publish (see Configuration → flitz.yaml) and carry keys of your own; sdk use rewrites only sdk: and preserves everything else. Keep the file valid YAML with string values: otherwise commands stop with <path>/flitz.yaml is not valid YAML (exit 1), and flitz status names the file. Fix it by hand, or delete it and run flitz sdk use <tag> again.

Re-running sdk use for a cached tag still contacts the service to resolve the tag, so it needs the network and an active license. Once an SDK is cached, the flutter and dart inside it work fully offline: the archive ships with everything they would otherwise download.

list

flitz sdk list

<tag>  (pinned)
<tag>

Local only; prints No SDKs cached. when the cache is empty. With --json: { "sdks": [ { "tag", "installed", "pinned" } ] }.

path

flitz sdk path
# /home/you/.cache/flitz/sdk/<tag>

Prints only the absolute cache path of the project's pinned SDK, on stdout, without contacting the service. It is a pure tag-to-path resolver, not a checker: it answers whether or not the SDK has been downloaded yet. That is what lets it sit in a shell profile that is evaluated before the SDK exists:

export PATH="$(flitz sdk path)/bin:$PATH"

Whether the tree is actually there is what flitz sdk list and flitz status report, and what publish enforces. With no pin in the current directory, sdk path prints nothing on stdout and exits 1.

--json adds the fact the bare form leaves out:

{ "tag": "<tag>", "path": "/home/you/.cache/flitz/sdk/<tag>", "installed": false }

Using the SDK as your flutter/dart

Publishing does not need the SDK on PATH — flitz publish resolves it from the cache by itself. But if you want to point an editor, a shell, or the host app's own build at the SDK, sdk path is how:

export PATH="$(flitz sdk path)/bin:$PATH"
flutter --version

flutter --version inside a Flitz SDK reports the full release tag, with its +flz.<N> suffix, as the framework version — that is how you tell a Flitz SDK from a stock Flutter checkout at a glance. Your host app must be built with the same tag the bundle is published with — see Loader plugins → Compatibility.

remove

flitz sdk remove <tag>

Deletes ~/.cache/flitz/sdk/<tag>/ and prints Removed <tag>.. Reports <tag> not cached. and still exits 0 when there was nothing to delete.

When it fails

Authorization, license, and network failures are the same as for every licensed command — see Troubleshooting.

Download integrity

• Verified. Every archive is checked against its published SHA-256 before it is placed. A mismatch names both digests, discards the download, and leaves the cache untouched.
• Resumable. An interrupted install/use continues from where it stopped rather than re-fetching the whole archive. Ctrl-C deliberately keeps the partial download.
• Serialized. Two concurrent installs of the same tag wait on a lock instead of corrupting each other's tree.
• Never damaged by failure. A failed or mismatched download never replaces, truncates, or deletes an already-installed SDK. --force is the only thing that replaces one.

Progress is reported as three phases — Downloading (with percentage, transferred-of-total, and rate), Verifying, and Extracting — so the largest transfer in the product is never silent.