# gpm login

Authenticate with GPM registry.

## Usage

```bash
gpm login [--registry <url>]
```

## Flags

| Flag               | Description                          | Default     |
| ------------------ | ------------------------------------ | ----------- |
| `--registry <url>` | Registry URL to authenticate against | From config |

## Description

Authenticates your GPM CLI with a registry server. This command stores authentication credentials securely for subsequent operations that require authentication (like publishing private packages).

### Authentication Process

1. **Interactive Login**: Prompts for username and password
2. **Credential Storage**: Stores token securely in OS keychain or encrypted file
3. **Registry Configuration**: Updates registry URL if specified
4. **Verification**: Validates authentication with the registry

### Secure Storage

GPM stores authentication tokens securely:

* **macOS**: OS Keychain
* **Linux**: OS Keychain (if available) or encrypted file
* **Windows**: Windows Credential Manager or encrypted file

### Registry Compatibility

GPM uses npm-compatible authentication via `PUT /-/user/org.couchdb.user:*` against the effective host.

## Examples

### Basic Authentication

```bash
# Login to default registry
gpm login

# Interactive prompt:
# Username: myusername
# Password: [hidden]
# Email: user@example.com
```

### Custom Registry

```bash
# Login to specific registry
gpm login --registry https://company.gpm.sh

# Interactive prompt:
# Username: myusername
# Password: [hidden]
# Email: user@example.com
```

## Output

### Successful Login

```
Authenticating with GPM Registry
───────────────────────────────────
Registry: https://registry.gpm.sh
───────────────────────────────────
Username: myusername
Password: [hidden]
Email: user@example.com
───────────────────────────────────
Successfully authenticated!
Token stored securely in keychain.
Registry configured: https://registry.gpm.sh
```

### Error Output

```
Error: Authentication failed: Invalid credentials
Hint: Check your username and password, or contact your registry administrator
```

## Authentication Flow

### Step-by-Step Process

1. **Registry Resolution**: Determine effective registry URL
2. **Credential Collection**: Prompt for username, password, and email
3. **API Authentication**: Send credentials to registry
4. **Token Storage**: Store received token securely
5. **Verification**: Test authentication with a simple API call

### API Endpoint

The login command makes a `PUT` request to:

```
PUT /-/user/org.couchdb.user:<username>
```

With payload:

```json
{
  "name": "username",
  "password": "password",
  "email": "user@example.com"
}
```

## Configuration Updates

After successful login, GPM updates your configuration:

### Registry URL

If `--registry` flag is provided, updates the registry setting:

```bash
gpm config set registry https://company.gpm.sh
```

### Token Storage

Stores the authentication token for the registry host:

* **Global registry**: Token for `registry.gpm.sh`
* **Tenant registry**: Token for `<tenant>.gpm.sh`

## Security Features

### Token Security

* Tokens are never logged or displayed
* Stored in OS keychain when available
* Fallback to AES-GCM encrypted local file
* Tokens are per-registry (isolated)

### Network Security

* HTTPS-only communication
* TLS certificate verification
* Proxy support via `HTTP_PROXY`/`HTTPS_PROXY`
* Timeout and retry policies

## Error Handling

### Common Errors

* **Invalid credentials**: `Authentication failed: Invalid credentials`
* **Network error**: `Failed to connect to registry`
* **Registry not found**: `Registry not found or unreachable`
* **Storage error**: `Failed to store authentication token`

### Troubleshooting

1. **Invalid credentials**: Verify username and password
2. **Network issues**: Check internet connection and registry URL
3. **Registry unreachable**: Verify registry URL and network access
4. **Storage issues**: Check keychain permissions or file system access

## Related Commands

* [`gpm logout`](https://github.com/gpm-sh/docs/blob/main/cli/authentication/logout.md) - Sign out from registry
* [`gpm whoami`](https://github.com/gpm-sh/docs/blob/main/cli/authentication/whoami.md) - Show current user information
* [`gpm config`](https://github.com/gpm-sh/docs/blob/main/cli/configuration/config.md) - Manage configuration settings

## See Also

* [Authentication Overview](https://github.com/gpm-sh/docs/blob/main/cli/authentication/README.md)
* [Registry Configuration](https://github.com/gpm-sh/docs/blob/main/packages/registry-resolution.md)
* [Security Best Practices](https://github.com/gpm-sh/docs/blob/main/troubleshooting/common-issues.md#security)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gpm.sh/cli-reference/cli/authentication/login.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.