# Examples

Practical examples and common workflows for using GPM CLI effectively.

## Quick Examples

{% hint style="success" %}
**Pro Tip**: Copy these examples directly into your terminal to get started quickly.
{% endhint %}

### Basic Package Operations

{% tabs %}
{% tab title="Add Packages" %}

```bash
# Add latest version
gpm add com.unity.analytics

# Add specific version
gpm add com.unity.analytics@2.1.0

# Add with engine specification
gpm add com.company.sdk --engine unity
```

{% endtab %}

{% tab title="Install Packages" %}

```bash
# Install from package.json
gpm install

# Install single package
gpm install com.unity.textmeshpro

# Install multiple packages
gpm install com.unity.analytics com.unity.timeline
```

{% endtab %}

{% tab title="Search Packages" %}

```bash
# Basic search
gpm search unity

# Search with limit
gpm search analytics --limit 20

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

{% endtab %}
{% endtabs %}

## Common Workflows

### Unity Development Workflow

### Publishing Workflow

### Team Collaboration

## Advanced Examples

### Registry Management

{% tabs %}
{% tab title="Multiple Registries" %}

```bash
# Switch to global registry
gpm config set registry https://registry.gpm.sh

# Switch to company registry
gpm config set registry https://company.gpm.sh

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

{% endtab %}

{% tab title="Authentication" %}

```bash
# Login to global registry
gpm login

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

# Check current user
gpm whoami

# Logout
gpm logout
```

{% endtab %}
{% endtabs %}

### Package Versioning

{% tabs %}
{% tab title="Version Ranges" %}

```bash
# Install latest version
gpm add com.unity.analytics

# Install specific version
gpm add com.unity.analytics@2.1.0

# Install version range
gpm add com.unity.analytics@^2.0.0
```

{% endtab %}

{% tab title="Distribution Tags" %}

```bash
# Publish with beta tag
gpm publish --tag=beta

# Publish with release tag
gpm publish --tag=release

# List distribution tags
gpm dist-tag list com.company.package

# Add custom tag
gpm dist-tag add com.company.package@1.0.0 stable
```

{% endtab %}
{% endtabs %}

## Error Handling Examples

### Common Error Scenarios

{% tabs %}
{% tab title="Package Not Found" %}

```bash
# Error: Package not found
gpm add com.nonexistent.package
# Error: package 'com.nonexistent.package' not found in registry

# Solution: Search for similar packages
gpm search nonexistent
```

{% endtab %}

{% tab title="Authentication Required" %}

```bash
# Error: Not authenticated
gpm publish --access=private
# Error: not authenticated. Run 'gpm login'

# Solution: Login first
gpm login
gpm publish --access=private
```

{% endtab %}

{% tab title="Invalid Package Name" %}

```bash
# Error: Invalid package name
gpm add @company/package
# Error: invalid package name: must use reverse-DNS format

# Solution: Use correct format
gpm add com.company.package
```

{% endtab %}
{% endtabs %}

## JSON Output Examples

### Using JSON Output for Scripting

{% tabs %}
{% tab title="Search Results" %}

```bash
# Get search results in JSON
gpm search unity --json --limit 5

# Example output:
{
  "success": true,
  "query": "unity",
  "total": 150,
  "results": [
    {
      "name": "com.unity.analytics",
      "version": "2.1.0",
      "description": "Analytics and insights for Unity games",
      "author": "Unity Technologies"
    }
  ]
}
```

{% endtab %}

{% tab title="Package Info" %}

```bash
# Get package information in JSON
gpm info com.unity.analytics --json

# Example output:
{
  "name": "com.unity.analytics",
  "version": "2.1.0",
  "description": "Analytics and insights for Unity games",
  "dependencies": {
    "com.unity.services.core": "1.10.1"
  }
}
```

{% endtab %}
{% endtabs %}

## Best Practices

### Package Management

{% hint style="info" %}
**Best Practice**: Always specify versions for production dependencies to ensure reproducible builds.
{% endhint %}

```bash
# Good: Specific version
gpm add com.unity.analytics@2.1.0

# Acceptable: Latest version (development)
gpm add com.unity.analytics

# Avoid: Unspecified versions in production
```

### Registry Configuration

{% hint style="warning" %}
**Security**: Never commit authentication tokens or sensitive registry URLs to version control.
{% endhint %}

```bash
# Good: Use environment variables
export GPM_REGISTRY=https://company.gpm.sh

# Avoid: Hardcoded sensitive URLs
gpm config set registry https://user:password@company.gpm.sh
```

### Error Handling

{% hint style="success" %}
**Pro Tip**: Use `--verbose` flag to get detailed error information for debugging.
{% endhint %}

```bash
# Get detailed error information
gpm add com.unity.analytics --verbose

# Check configuration
gpm config

# Verify authentication
gpm whoami
```

## Integration Examples

### CI/CD Integration

### Docker Integration

## Share Your Success Stories

### Community Showcases

Have you built something amazing with GPM? Share your success stories with the community:

* **GitHub**: [Submit examples](https://github.com/gpm-sh/gpm-cli) - Contribute to the documentation
* **Reddit**: [r/gamedev success stories](https://reddit.com/r/gamedev) - Inspire other developers
* **Unity Forums**: [Package management showcase](https://forum.unity.com/forums/package-manager.25/) - Unity-specific examples

### Professional Case Studies

Leading game development studios share their GPM success stories:

* **GameDev.net**: [Studio workflow optimization](https://gamedev.net) - Enterprise case studies
* **Unity Blog**: [Multi-engine development success](https://blog.unity.com) - Unity + GPM stories
* **Godot Community**: [Addon management workflows](https://godotengine.org) - Godot success stories
* **Unreal Engine**: [Plugin management at scale](https://unrealengine.com) - Unreal enterprise stories

## See Also

* [CLI Reference](/cli-reference/cli.md) - Complete command documentation
* [Package Management](/cli-reference/cli/package-management.md) - Package management guides
* [Publishing](/cli-reference/cli/publishing.md) - Publishing workflows
* [Troubleshooting](/troubleshooting/troubleshooting.md) - Common issues and solutions


---

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