Configuration

Where a setting comes from

Highest wins:

1. A command-line flag — --profile, --workspace/-w, --project, --api-url
2. An environment variable — LAYER_PROFILE, LAYER_WORKSPACE, LAYER_PROJECT, LAYER_API_URL, LAYER_API_KEY
3. layer.toml, found by walking up from the working directory
4. The active profile in ~/.layer/config.toml

Pin a checkout to its workspace

Commit a layer.toml at the root of a repository and every layer command run inside it acts on that workspace and project — no flag to remember, and two repos open in two terminals cannot generate into each other’s:

workspace = "my-studio"
project   = "season-12-art"

Tip

layer.toml names a workspace, never a credential. It is safe to commit; LAYER_API_KEY is not.

Profiles

A profile bundles a deployment and the credential for it. The default is production; add more when you work against several at once:

layer --profile staging login
layer --profile staging whoami
export LAYER_PROFILE=staging     # for a whole shell session

Each profile carries its own credential, and layer login pins the profile to the deployment it signed in to — so switching profiles switches both at once.

Profiles live in ~/.layer/config.toml. Tokens do not: they are in your operating system keychain.

Talking to another deployment

layer --api-url https://api.dev.layer.ai generate image -p "..."

Or LAYER_API_URL for a whole session. A profile that was signed in against one deployment will not authenticate against another, so pair this with its own profile.