# `bird auth login`

## Usage

```bash
bird auth login [flags]
```

## Description

Authenticate as yourself via the browser. The CLI opens a consent page
where you pick a workspace and the permissions to grant; the resulting token
acts as you, capped to that workspace and those scopes.

By default login requests a read-only baseline (the everyday surfaces at read).
A command that needs more prints the exact re-login to run; that step-up
accumulates into your grant, so you never lose access you already had. Pass
--scope to request a specific set, or --yolo for the full delegable catalogue.

Headless or SSH sessions (and --device) use the device flow instead: the CLI
prints a code and URL to enter on another device.

Both flows block until you approve, then time out after a few minutes. On
success the credential is written to ~/.config/bird/credentials.json (its path
is printed); re-run to switch workspace — login overwrites the stored credential.

## Examples

```bash
  # Browser login (default: read-only baseline)
  bird auth login

  # Everything you're allowed to grant
  bird auth login --yolo

  # Headless / SSH: device flow
  bird auth login --device

  # Request a specific set of scopes
  bird auth login --scope emails:write --scope domains:read
```

## Options

| Name                | Description                                                             |
| ------------------- | ----------------------------------------------------------------------- |
| `--device`          | Use the device authorization flow (no local browser)                    |
| `--scope <v1,v2,…>` | OAuth scope to request (repeatable); defaults to the read-only baseline |
| `--yolo`            | Request the full delegable scope set instead of the baseline            |

## Related

| Name                                                              | Description                                                              |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [`bird auth create-org`](/docs/cli/reference/auth-create-org)     | Create the first organization and workspace and mint your credential.    |
| [`bird auth logout`](/docs/cli/reference/auth-logout)             | Revoke the OAuth grant (if any) and remove the stored credentials file   |
| [`bird auth signup`](/docs/cli/reference/auth-signup)             | Start a passwordless Bird signup and email a six-digit code.             |
| [`bird auth status`](/docs/cli/reference/auth-status)             | Show current authentication state and validate the token against the API |
| [`bird auth verify-email`](/docs/cli/reference/auth-verify-email) | Confirm the emailed six-digit code and sign in.                          |