Configuration

How the CLI resolves its API URL, key and project: flags, environment variables and the config file.

The CLI has three settings that matter: the API URL, the API key and the project. Each one resolves in the same order:

flag > environment variable > config file > default

The API key is the exception: it’s never read from the config file. It comes from --api-key, WINDPAINT_API_KEY, or the credentials file written by auth login.

Config file

~/.windpaint/config.yaml is optional. A missing file is the same as an empty one.

# ~/.windpaint/config.yaml
api:
  url: https://api.windpaint.ai
project: launch-video

Edit the file by hand or let projects select manage project. There’s no config set command.

The config directory holds two files:

--config moves only config.yaml. --config-dir moves both, which is useful for keeping separate setups side by side:

WINDPAINT_CONFIG_DIR=~/.windpaint-client-a windpaint auth login --api-key aak_...
WINDPAINT_CONFIG_DIR=~/.windpaint-client-a windpaint balance

Environment variables

Global flags

Every command accepts these.

See Scripting and agents for how output modes and stderr work.

Project selection

Every generation request, upload, asset and product run belongs to a project. The CLI sends the selected project as the X-Windpaint-Project header; with no project set, the API uses your organization’s default project. See Organizations and projects.

The project resolves from, highest first:

1. --project on the command
2. WINDPAINT_PROJECT
3. project in config.yaml, written by windpaint projects select
4. Your organization’s default project

Save a default once:

windpaint projects select launch-video

Selected project launch-video (5b0c2d7e-8f61-4c1a-9e3d-2a7b6c4f8e90)

select checks that the project exists and isn’t archived, then saves its slug. Clear it to go back to the organization default:

windpaint projects select --clear

Override it for one command:

windpaint assets --project product-shots

Show the resolved configuration

windpaint config show

API URL      https://api.windpaint.ai (default)
API key      aak_…9f3e (env)
Project      launch-video (config)
Config file  /Users/you/.windpaint/config.yaml
Config dir   /Users/you/.windpaint

Each value shows where it came from: flag, env, config, credentials (the API key saved by auth login) or default. The key is redacted to its first and last four characters. When no project is set, Project reads API key default, meaning the API picks your organization’s default project.

Run this first when a command uses the wrong key or project. config show doesn’t call the API, so it works offline and without a key.

With --json:

{
  "api_key": "aak_…9f3e",
  "api_url": "https://api.windpaint.ai",
  "config_dir": "/Users/you/.windpaint",
  "config_file": "/Users/you/.windpaint/config.yaml",
  "project": "launch-video",
  "sources": {
    "api_key": "env",
    "api_url": "default",
    "project": "config"
  }
}

Next