> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bonya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# login

> Authenticate the CLI, either via your browser or with an existing API key

## `bonya login`

Saves an API key (and optionally an endpoint and organization id) to the local config file, so subsequent commands don't need `--api-key`/`--endpoint`/`--organization-id` or `BONYA_API_KEY`/`BONYA_ENDPOINT`/`BONYA_ORGANIZATION_ID`. Flags and environment variables still take priority over what's saved — see [Configuration](https://docs.bonya.ai/cli-reference/configuration.md) for the full precedence order.

There are two ways to log in:

> [tab] Browser (default)
>
> Run `bonya login` with no `--api-key`. This is a device-authorization flow — the same shape as `gh auth login`:
>
> ```shell theme={null}
> bonya login
> ```
>
> It mints a login request, prints (and opens) a verification URL, and polls until you approve the login there. Nothing to copy or paste. The resulting API key is saved automatically.
>
> ```console theme={null}
> $ bonya login
> Opening https://bonya.ai/device?... in your browser.
> If it doesn't open automatically, visit: https://bonya.ai/device?...
> Waiting for approval...
> Logged in as you@example.com
> Saved login to /Users/you/.config/bonya/config.json
> ```

> [tab] API key
>
> Pass `--api-key` directly — useful for CI, or when you already have a key:
>
> ```shell theme={null}
> bonya login --api-key byk_...
> bonya login --api-key byk_... --endpoint https://api.bonya.ai --organization-id org-...
> ```
>
> This path makes one bounded `list` call (`Limit: 1`) to confirm the key actually works before saving it. Pass `--skip-verify` to save without that check.

If your account has no sandboxes yet, `bonya login` offers to create your first one and tells you how to open a shell in it.

## Flags

| Flag | Default | Description |
| - | - | - |
| `--api-key` | — | API key to save. Setting this skips the browser flow entirely. |
| `--endpoint` | — | Endpoint to save alongside the API key (optional). |
| `--organization-id` | — | Organization id to save alongside the API key (optional). |
| `--skip-verify` | `false` | Save without making a request to verify the API key first. Only applies to the `--api-key` path. |
| `--no-browser` | `false` | Print the login URL instead of opening it automatically (e.g. over SSH). Only applies to the browser flow. |
| `--timeout` | server-provided expiry | How long to wait for browser approval before giving up. Only applies to the browser flow. |

> [!NOTE]
>
> `--skip-verify` and `--no-browser` each only affect one of the two login paths: `--skip-verify` does nothing without `--api-key`, and `--no-browser` does nothing *with* it (the `--api-key` path never opens a browser in the first place).

## Examples

```shell Browser login theme={null}
bonya login
```

```shell Over SSH (print, don't open) theme={null}
bonya login --no-browser
```

```shell Custom approval timeout theme={null}
bonya login --timeout 2m
```

```shell CI / scripted theme={null}
bonya login --api-key "$BONYA_API_KEY" --skip-verify
```

## After logging in

```shell theme={null}
bonya whoami    # shows where each setting currently resolves from
bonya logout    # removes the saved login
```

See [`whoami` and `logout`](https://docs.bonya.ai/cli-reference/account) and [`bonya org`](https://docs.bonya.ai/cli-reference/org) for switching which organization your commands act in.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.