# 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:

```toml
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:

```bash
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

```bash
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.