Authentication

Sign the CLI in with an API key or your email and password, and override it in CI.

The CLI authenticates every request with a Windpaint API key (aak_...). Create one in the dashboard under Settings → API Keys; see API keys. The key acts in your organization with your role.

Log in with an API key

windpaint auth login --api-key aak_...

Saved credentials to /Users/you/.windpaint
Login successful

auth login checks the key against the API before saving it, so a mistyped or revoked key fails here (exit code 3) rather than on your first generation.

To keep the key out of your shell history, pass - and pipe it in. The CLI reads the first line of stdin:

echo "$WINDPAINT_KEY" | windpaint auth login --api-key -

Log in with email and password

windpaint auth login --email [email protected]

The CLI prompts for your password without echoing it. In a non-interactive shell there’s no prompt, so pass --password as well, or use an API key.

Password login saves a session token instead of an API key. Session tokens expire and the CLI doesn’t refresh them, so when commands start failing with exit code 3, run auth login again. Accounts that sign in with Google or GitHub have no password and must use an API key. For scripts, CI and agents, always use an API key.

Check who you are

windpaint auth whoami

email       [email protected]
name        Jane Doe
id          6c1f0f0e-2a4b-4f7e-9d0a-3b2f1e8c4d21

Run windpaint config show to see which key is in use and where it came from. See Configuration.

Log out

windpaint auth logout

This deletes the saved credentials file. It doesn’t revoke the key on the server, and it doesn’t affect a key passed with --api-key or WINDPAINT_API_KEY. To revoke a key, use Settings → API Keys in the dashboard.

Where credentials live

auth login writes ~/.windpaint/credentials.json, readable only by your user (mode 0600, in a 0700 directory):

{
  "api_key": "aak_..."
}

The key is never read from or written to config.yaml. If you set a different config directory with --config-dir or WINDPAINT_CONFIG_DIR, the credentials file lives there instead.

CI and other non-interactive environments

Don’t run auth login in CI. Set WINDPAINT_API_KEY from your secret store instead, and nothing is written to disk:

export WINDPAINT_API_KEY=aak_...
windpaint run image.generate "a lighthouse at dusk" -o ./out/

The CLI picks the key from, highest first:

1. --api-key on the command
2. WINDPAINT_API_KEY
3. credentials.json from auth login

With none of these, any command that calls the API exits with code 3 and the hint run 'windpaint auth login', set WINDPAINT_API_KEY, or pass --api-key.

Next