# Registry Operations

Search and browse packages in GPM registries with powerful discovery and information tools.

## Overview

GPM provides comprehensive registry operations for discovering, researching, and managing packages across multiple registries. The system supports both global and tenant registries with advanced search and filtering capabilities.

## Commands

| Command                                               | Description              | Usage                |
| ----------------------------------------------------- | ------------------------ | -------------------- |
| [`gpm search`](/cli-reference/cli/registry/search.md) | Search for packages      | `gpm search <term>`  |
| [`gpm info`](/cli-reference/cli/registry/info.md)     | Show package information | `gpm info <package>` |

## Quick Start

### Package Discovery

```bash
# Search for packages
gpm search unity

# Search with limit
gpm search analytics --limit 20

# Detailed search results
gpm search ui --detail
```

### Package Information

```bash
# Show package info
gpm info com.unity.analytics

# Show specific version
gpm info com.unity.analytics --version 2.1.0

# JSON output
gpm info com.unity.analytics --json
```

## Registry Types

### Global Registry

* **URL**: `https://registry.gpm.sh`
* **Access**: Public packages only
* **Search**: All public packages
* **Info**: Public package information

### Tenant Registries

* **URL**: `https://<tenant>.gpm.sh`
* **Access**: Scoped and private packages
* **Search**: Tenant-specific packages
* **Info**: Tenant package information

## Search Capabilities

### Basic Search

```bash
# Search by name
gpm search unity

# Search by description
gpm search analytics

# Search by keywords
gpm search ui framework
```

### Advanced Search

```bash
# Search with limit
gpm search unity --limit 50

# Detailed search results
gpm search analytics --detail

# JSON output for scripting
gpm search unity --json
```

### Search Results

Search results include:

* **Package Name**: Full package identifier
* **Version**: Latest available version
* **Description**: Package description
* **Author**: Package author
* **Keywords**: Package keywords
* **Relevance Score**: Search relevance percentage

## Package Information

### Comprehensive Details

Package information includes:

* **Metadata**: Name, description, author, license
* **Version Information**: Latest version, available versions
* **Distribution Tags**: Available distribution tags
* **Dependencies**: Package dependencies and versions
* **Registry Details**: Tarball URL, integrity hash
* **Unity Information**: Unity version requirements

### Version Management

```bash
# Latest version
gpm info com.unity.analytics

# Specific version
gpm info com.unity.analytics --version 2.1.0

# Version comparison
gpm info com.unity.analytics --version 2.0.0
gpm info com.unity.analytics --version 2.1.0
```

## Registry Configuration

### Default Registry

```bash
# Check current registry
gpm config get registry

# Set global registry
gpm config set registry https://registry.gpm.sh
```

### Tenant Registry

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

# Search tenant packages
gpm search company-package
```

### Registry Override

```bash
# Override registry for single command
gpm search unity --registry https://custom.gpm.sh
gpm info com.package --registry https://custom.gpm.sh
```

## Access Control

### Public Packages

* **Search**: Available without authentication
* **Info**: Available without authentication
* **Installation**: Available without authentication

### Scoped Packages

* **Search**: Available without authentication (on tenant registry)
* **Info**: Available without authentication (on tenant registry)
* **Installation**: Available without authentication (on tenant registry)

### Private Packages

* **Search**: Available with authentication (on tenant registry)
* **Info**: Available with authentication (on tenant registry)
* **Installation**: Available with authentication (on tenant registry)

## Common Workflows

### Package Discovery

```bash
# 1. Search for packages
gpm search unity analytics

# 2. Get detailed information
gpm info com.unity.analytics

# 3. Check dependencies
gpm info com.unity.analytics --verbose

# 4. Install package
gpm install com.unity.analytics
```

### Package Research

```bash
# 1. Research package before installation
gpm info com.unity.analytics

# 2. Check version compatibility
gpm info com.unity.analytics --version 2.1.0

# 3. Verify package integrity
gpm info com.unity.analytics --json | jq '.distribution.integrity'
```

### Team Collaboration

```bash
# 1. Search for team packages
gpm search company --registry https://company.gpm.sh

# 2. Get package information
gpm info com.company.package --registry https://company.gpm.sh

# 3. Install team package
gpm install com.company.package --registry https://company.gpm.sh
```

## Advanced Features

### JSON Output

```bash
# Search results in JSON
gpm search unity --json

# Package info in JSON
gpm info com.unity.analytics --json

# Process JSON output
gpm search unity --json | jq '.results[] | .name'
```

### Filtering and Sorting

```bash
# Search with limit
gpm search unity --limit 10

# Detailed search results
gpm search analytics --detail

# Sort by relevance
gpm search unity --json | jq '.results | sort_by(.score) | reverse'
```

### Registry Comparison

```bash
# Compare packages across registries
gpm search unity --registry https://registry.gpm.sh
gpm search unity --registry https://company.gpm.sh
```

## Error Handling

### Common Errors

* **Package not found**: `Package 'com.example.package' not found`
* **Version not found**: `Version '1.0.0' not found for package`
* **Registry error**: `Failed to fetch package information`
* **Network error**: `Failed to connect to registry`

### Troubleshooting

1. **Package not found**: Check package name and registry
2. **Version not found**: Check available versions with search
3. **Registry error**: Verify registry URL and network connectivity
4. **Network error**: Check internet connection and proxy settings

## Best Practices

### Package Discovery

```bash
# Use specific search terms
gpm search unity analytics  # Good
gpm search analytics        # Less specific

# Use appropriate limits
gpm search unity --limit 20  # Good for browsing
gpm search unity --limit 5   # Good for specific results
```

### Package Research

```bash
# Always check package info before installation
gpm info com.unity.analytics
gpm install com.unity.analytics

# Verify package integrity
gpm info com.unity.analytics --json | jq '.distribution.integrity'
```

### Registry Management

```bash
# Use appropriate registry for package type
gpm search unity --registry https://registry.gpm.sh        # Public packages
gpm search company --registry https://company.gpm.sh       # Company packages
```

## Integration Examples

### CI/CD Integration

```bash
# Check package availability in CI
gpm info com.unity.analytics --json | jq '.success'

# Search for packages in CI
gpm search unity --json | jq '.results | length'
```

### Scripting

```bash
# Get package versions
gpm info com.unity.analytics --json | jq '.version'

# Search and install
gpm search unity --json | jq -r '.results[0].name' | xargs gpm install
```

## Related Commands

* [Package Management](/cli-reference/cli/package-management.md) - Package installation and management
* [Publishing](/cli-reference/cli/publishing.md) - Package publishing
* [Authentication](/cli-reference/cli/authentication.md) - User authentication

## See Also

* [Package Guidelines](https://github.com/gpm-sh/docs/blob/main/packages/README.md) - Package naming and structure
* [Access Levels](/package-guidelines/packages/access-levels.md) - Package visibility controls
* [Registry Resolution](https://github.com/gpm-sh/docs/blob/main/packages/registry-resolution.md) - Registry configuration


---

# 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/registry.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.