picto.yaml & Flavors

Keep each build flavor's API key in one file instead of copying them out of the dashboard.

A picto.yaml file at your project's root records one API key per build flavor, so you have a single place to read them from instead of going back to the dashboard every time. It is written for you by picto:setup and picto:init.

Generating one interactively#

dart run picto:setup

This signs in to your dashboard account, lists the organizations and client apps it owns, and lets you pick one (or create a new client app on the spot) — then writes the result into picto.yaml for you. Run it again to add another flavor to the same file; it won't disturb flavors you've already saved.

Already have real Android/iOS build flavors set up in your project? dart run picto:init detects them and creates a client app for every one in a single pass, instead of walking through this flow once per flavor.

The file itself#

defaultFlavor: "dev"
flavors:
  dev:
    apiKey: "oc_..."
  prod:
    apiKey: "oc_..."

Key	Meaning
`flavors`	One or more named entries, each holding the `apiKey` of its own client app. At least one is required.
`defaultFlavor`	Optional. Recorded when a project has more than one flavor.
`endpoint`	Optional, and normally absent — omit it and every flavor talks to the hosted picto backend. Setting it points them somewhere else instead, which is what a local development backend needs.

A flavor entry is just an API key. It used to also carry clientAppId and ownerId; both were removed once the server started deriving them from the key alone, so tracking them next to it was redundant. If you are looking at an older picto.yaml that still lists them, they are ignored — delete them.

Flavors#

A flavor is a name (e.g. dev, staging, prod) mapped to its own client app — the same isolation boundary the dashboard already uses, not a new concept. This keeps recordings and uploaded assets from different environments from landing in the same place: a dev build and a prod build use two different API keys, so their recordings, assets, and dashboard views never mix.

What actually reads this file#

Worth being precise about, because it is less than the layout suggests:

Reader	What it uses
`picto:setup`, `picto:init`	Read the whole file to merge new flavors into it, and write it back.
`picto:upload_assets`	Reads only `endpoint` . It authenticates with your dashboard email and password, and takes client apps from `--client-app-id` , so it never reads `flavors` .
The recording SDK	Nothing. It is given its API key at build time via `RECORDING_API_KEY` — see Installation .

So flavors and defaultFlavor are a record for you, not configuration any command resolves today. Copy the key for the flavor you're building into that build's dart-define.

There is no --flavor flag on any picto command. One existed while upload_assets authenticated with an API key; it was removed on 2026-07-31 when the script moved to signing in with an account instead, and nothing has read defaultFlavor for selection since.