# gram auth

The `auth` command authenticates with the platform by opening a browser
window for login. After successful authentication, it creates and saves a
[producer API key](/docs/ai-control-plane/org-admin/api-keys) for the local
profile configuration.

<Callout type="info">
    The `gram auth` command is typically run once during initial setup. The
    API key and profile information it creates are stored in
    `~/.gram/profile.json`.
</Callout>

## Usage

Authenticate from the CLI:

```bash
gram auth
```

This command will:

- Open a browser window to the platform authentication page
- Prompt for login credentials
- Create a producer API key in the dashboard
- Save the API key and profile information locally
- Save the project selected in the browser as the default project

If the local profile already contains a valid API key, `gram auth` refreshes
the profile without opening a browser window.

After authentication, verify the setup with [`gram whoami`](/docs/ai-control-plane/reference/command-line/whoami).

## Subcommands

Change the default project context:
```bash
gram auth switch --project {project-slug}
```

Completely clear auth information in the local profile to allow a fresh `gram auth`:
```bash
gram auth clear
```

## Options

### <code>api-url</code>

This option sets the URL of the API server. It's useful for connecting to
custom or self-hosted instances.

```bash
gram auth --api-url https://custom.gram.instance [other options]
```

The API server URL can also be set via the `GRAM_API_URL` environment variable.

### <code>dashboard-url</code>

This option sets the URL of the dashboard used for browser-based
authentication. If not provided, it defaults to the API server URL.

```bash
gram auth --dashboard-url https://custom.gram.instance [other options]
```

The dashboard URL can also be set via the `GRAM_SITE_URL` environment variable.