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.