Apps and tracks

Every flitz publish lands in your organization's history under an app and one of its tracks. An app usually stands for one Flutter project, and a track for one Git branch, so every branch gets a link that always opens its newest build.

organization
└── app        acme_app       download access · live, archived, or deleted
    └── track  feature-login  the branch feature/login · the track link
        └── publish           one build · landing page, deeplink, bundle

The portal shows the same tree, and the flitz apps, flitz tracks, and flitz publishes commands read and manage it. In a host with the panel, teammates browse it on the device.

Apps

An app has a key and a display name:

• The key is 1–100 letters, digits, _, or -. It is what you type — app: in flitz.yaml, --app, flitz apps … — and it is part of every track link. By default it is the name: in your pubspec.yaml.
• The display name shows on landing pages, in the portal, and in the panel. A new app's name is its key until someone renames it.

The first publish under your pubspec name creates the app without asking. A key you name yourself, with --app or app:, is created only after you confirm it, or with --yes in CI — so a typo does not quietly start a new app.

Each app also has a download access setting and a state: live, archived, or deleted — see Archive, delete, and restore.

Pro includes one app. More than one app is part of Flitz Enterprise.

Tracks

A track is one line of builds within an app, normally your Git branch.

• A track is created by its first publish. Its name is the branch name. Its key is the branch name with every character other than letters, digits, _, and - replaced by -, so feature/login becomes feature-login. Branches whose names give the same key share one track.
• Publishes made without a branch — from a detached checkout, as in most CI jobs, or from a folder outside Git — land on the app's Unassigned track. In CI, pass the branch with --track.
• You can name the track yourself with --track, or track: in flitz.yaml.

flitz publish takes the app from --app, then app:, then the pubspec name:, and the track from --track, then track:, then the current branch — see App, track, and scheme.

Links

flitz publish prints four links:

The first three belong to one publish. The track link follows the track, so you can share it once and teammates get every later build from it. When the newest build is deleted, the track link moves to the previous complete one.

• Links have no expiry date. They work as long as the publish and its app exist — after your license lapses, after the person who published leaves the organization, and after the API key rotates. Deleting the publish or the app stops them.
• Per-publish links end in a random suffix, and nothing lists them publicly. A track link is built from your organization, the app key, and the branch name, so someone who has seen one of your links can work it out.
• A new app key breaks track links. Renaming an app's key stops the track links shared before; per-publish links keep working.

Download access

Each app decides who can download its builds:

• The Owner and Admins change it on the app's page in the portal. Members see it but cannot change it, and the CLI cannot change it; flitz apps list --json shows it.
• It covers every publish of the app, links already shared included, and the app's track links. A change applies from the next download.
• Landing and track pages still open for anyone. For a Members only app they say the build opens only in the organization's own app, for a signed-in member.
• On a device, a refused build shows Members only or Can't open builds with this account — see Members only.

With Anyone with the link, share links the way you share a build of your app: a bundle runs with the full privileges of the host. Use Members only when an app's builds must stay inside your organization.

Archive, delete, and restore

Any member can change an app, from its page in the portal or with flitz apps — signed in with flitz login, not with the organization's API key.

Deleting a single publish is final: it leaves the history, its links stop working, and nothing restores it.

Where to manage them