# gpm search

Search for packages in the GPM registry.

## Usage

```bash
gpm search <term> [flags]
```

## Arguments

* `<term>` - Search term (package name, description, keywords)

## Flags

| Flag               | Description                       | Default     |
| ------------------ | --------------------------------- | ----------- |
| `--limit <number>` | Maximum number of results to show | `10`        |
| `--detail`         | Show detailed package information | `false`     |
| `--registry <url>` | Override registry URL             | From config |
| `--json`           | Output results in JSON format     | `false`     |

## Description

Searches for packages in the GPM registry using the search term. The search looks through package names, descriptions, and keywords to find relevant packages.

### Search Scope

The search command searches across:

* Package names
* Package descriptions
* Package keywords
* Author information

### Registry Endpoint

Uses the registry search API:

```
GET /-/v1/search?text=<term>&size=<limit>&from=<offset>
```

## Examples

### Basic Search

```bash
# Search for packages
gpm search unity

# Search with limit
gpm search analytics --limit 20

# Search with detailed output
gpm search ui --detail
```

### Advanced Search

```bash
# Search in custom registry
gpm search package-name --registry https://company.gpm.sh

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

## Output

### Human Format (Default)

```
Package Search
──────────────────
Search term: unity
──────────────────

Found 15 packages:

com.unity.analytics (2.1.0)
   Analytics and insights for Unity games
   Author: Unity Technologies
   Keywords: unity, analytics, insights, telemetry

com.unity.textmeshpro (3.0.6)
   Advanced text rendering for Unity
   Author: Unity Technologies
   Keywords: unity, text, ui, rendering

com.unity.timeline (1.7.4)
   Timeline and Cinemachine for Unity
   Author: Unity Technologies
   Keywords: unity, timeline, cinemachine, animation

... and 12 more packages
```

### Detailed Format (`--detail`)

```
Package Search
──────────────────
Search term: analytics
──────────────────

com.unity.analytics (2.1.0)
   Description: Analytics and insights for Unity games
   Author: Unity Technologies
   License: Unity Companion License
   Keywords: unity, analytics, insights, telemetry
   Repository: https://github.com/Unity-Technologies/analytics
   Downloads: 1,234,567
   Last Updated: 2024-01-15

   Dependencies:
   - com.unity.services.core@1.10.1
   - com.unity.nuget.newtonsoft-json@3.2.1
```

### JSON Format (`--json`)

```json
{
  "success": true,
  "query": "unity",
  "total": 15,
  "results": [
    {
      "name": "com.unity.analytics",
      "version": "2.1.0",
      "description": "Analytics and insights for Unity games",
      "author": "Unity Technologies",
      "keywords": ["unity", "analytics", "insights", "telemetry"],
      "downloads": 1234567,
      "lastUpdated": "2024-01-15T10:30:00Z"
    }
  ]
}
```

## Search Tips

### Effective Search Terms

* **Package names**: `com.unity.analytics`
* **Keywords**: `analytics`, `ui`, `networking`
* **Descriptions**: `text rendering`, `game analytics`
* **Partial matches**: `unity`, `analytics`

### Search Examples

```bash
# Search by package name
gpm search com.unity.analytics

# Search by functionality
gpm search analytics

# Search by engine
gpm search unity

# Search by UI components
gpm search ui --limit 25
```

## Error Handling

### Common Errors

* **Network error**: `Failed to connect to registry`
* **Registry not found**: `Registry not found or unreachable`
* **Invalid search term**: `Search term cannot be empty`
* **No results**: `No packages found matching 'term'`

### Troubleshooting

1. **No results**: Try broader search terms or check spelling
2. **Network issues**: Check internet connection and registry URL
3. **Registry unreachable**: Verify registry configuration

## Related Commands

* [`gpm info`](https://github.com/gpm-sh/docs/blob/main/cli/registry/info.md) - Get detailed package information
* [`gpm install`](/cli-reference/cli/package-management/install.md) - Install found packages
* [`gpm add`](/cli-reference/cli/package-management/add.md) - Add packages to project

## See Also

* [Registry Operations Overview](https://github.com/gpm-sh/docs/blob/main/cli/registry/README.md)
* [Package Information](https://github.com/gpm-sh/docs/blob/main/cli/registry/info.md)
* [Package Installation](/cli-reference/cli/package-management/install.md)


---

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