# Authentication Commands

Manage authentication with GPM registries for secure package operations.

## Overview

GPM provides secure authentication for accessing private and scoped packages. The authentication system supports multiple registries and stores credentials securely using OS keychain or encrypted files.

## Commands

| Command                                                     | Description                   | Usage                           |
| ----------------------------------------------------------- | ----------------------------- | ------------------------------- |
| [`gpm login`](/cli-reference/cli/authentication/login.md)   | Authenticate with registry    | `gpm login [--registry <url>]`  |
| [`gpm logout`](/cli-reference/cli/authentication/logout.md) | Clear authentication token    | `gpm logout [--registry <url>]` |
| [`gpm whoami`](/cli-reference/cli/authentication/whoami.md) | Show current user information | `gpm whoami [--registry <url>]` |

## Authentication Flow

### 1. Login Process

```bash
# Login to default registry
gpm login

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

### 2. Verify Authentication

```bash
# Check current user
gpm whoami
```

### 3. Perform Authenticated Operations

```bash
# Publish private package
gpm publish --access=private

# Publish scoped package
gpm publish --access=scoped
```

### 4. Logout When Done

```bash
# Clear authentication
gpm logout
```

## Registry Types

### Global Registry

* **URL**: `https://registry.gpm.sh`
* **Access**: Public packages only
* **Authentication**: Required for publishing

### Tenant Registries

* **URL**: `https://<tenant>.gpm.sh`
* **Access**: Scoped and private packages
* **Authentication**: Required for private packages

## Security Features

### Secure Storage

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

### Token Management

* Tokens are never logged or displayed
* Per-registry token isolation
* Automatic token validation
* Secure token removal on logout

### Network Security

* HTTPS-only communication
* TLS certificate verification
* Proxy support via environment variables
* Timeout and retry policies

## Access Levels

### Public Packages

* No authentication required for reading
* Authentication required for publishing
* Available on global registry

### Scoped Packages

* No authentication required for reading (on tenant registry)
* Authentication required for publishing
* Available on tenant registries

### Private Packages

* Authentication required for reading and publishing
* Available on tenant registries only
* Maximum security for proprietary packages

## Common Workflows

### Development Setup

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

# 2. Verify authentication
gpm whoami

# 3. Install private packages
gpm install com.company.private-sdk

# 4. Publish new package
gpm publish --access=scoped
```

### CI/CD Authentication

```bash
# 1. Set authentication token
export GPM_TOKEN="your-token-here"

# 2. Configure registry
gpm config set registry https://company.gpm.sh

# 3. Install packages
gpm install
```

### Team Collaboration

```bash
# 1. Login to shared registry
gpm login --registry https://team.gpm.sh

# 2. Install team packages
gpm install com.team.shared-utils

# 3. Publish team package
gpm publish --access=scoped
```

## Troubleshooting

### Common Issues

* **Authentication failed**: Check username and password
* **Token expired**: Re-login to refresh token
* **Registry not found**: Verify registry URL
* **Permission denied**: Check keychain/file permissions

### Debug Steps

1. Check authentication status: `gpm whoami`
2. Verify registry configuration: `gpm config get registry`
3. Test network connectivity: `gpm search test`
4. Clear and re-authenticate: `gpm logout && gpm login`

## See Also

* [Registry Configuration](https://github.com/gpm-sh/docs/blob/main/packages/registry-resolution.md)
* [Access Levels](/package-guidelines/packages/access-levels.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.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.