---
title: "auth login"
description: "Authenticate with PgBeam"
canonical: "https://pgbeam.com/docs/cli/auth/login"
last-updated: "2026-10-29T19:01:20.000Z"
---

# auth login

> Authenticate with PgBeam

URL: https://pgbeam.com/docs/cli/auth/login

{/* Auto-generated from CLI commands. Do not edit. Run `pnpm generate:cli-docs` to regenerate. */}

Authenticate with PgBeam to access your projects and databases. Login uses an API key, which you generate from the PgBeam dashboard under Settings > API Keys; running the command prompts you to paste it. The key is verified against the API before it is stored (an invalid key fails the login), and your organization is resolved automatically: a single visible organization is selected for you, multiple organizations prompt a pick. Credentials are stored in a local profile on disk (`~/.config/pgbeam/`), and the profile you log into becomes the active one for subsequent commands. You can maintain multiple profiles for different environments using the `--profile` flag, and move between them with `pgbeam auth switch`.

## Usage

```bash
pgbeam auth login [flags]
```

## Options

| Option      | Description                                                | Required | Default |
| ----------- | ---------------------------------------------------------- | -------- | ------- |
| `--api-key` | Authenticate with an API key (the default and only method) | No       | `false` |

> **Global options**
>
> All [global options](/docs/cli/global-options) (`--token`, `--profile`,
> `--project`, `--org`, `--json`, `--no-color`, `--no-trunc`, `--debug`) are
> also available on this command.

## Examples

```bash
# Login with an API key (prompts for the key)
pgbeam auth login

# Login with an API key and save to a named profile
pgbeam auth login --profile production
```

## Output

On success, prints a confirmation with the authenticated profile name and the selected organization, ready for `pgbeam projects list`. When the login replaces a different active profile, it also names the profile it switched from. The token is stored locally and used for all subsequent commands. A key the API rejects (401) is not stored and the command exits non-zero.