### Build Examples

Source: https://docs.gpm.sh/cli-reference/cli/utilities/version

Examples of build metadata output.

```bash
# Development build
gpm version
# Commit: 754da3a
# Built: 2025-09-14_09:39:23

# Release build
gpm version
# Commit: a1b2c3d
# Built: 2025-09-14_10:00:00
```

--------------------------------

### Initialize a New UPM Package Interactively

Source: https://docs.gpm.sh/cli-reference/cli/project/init

Use this command to start a new package with prompts for configuration details. It's useful for guided setup.

```bash
gpm init
```

```bash
# Interactive prompts:
# Package name: com.company.mypackage
# Description: My awesome Unity package
# Author: John Doe
# License: MIT
# Unity version: 2021.3
```

--------------------------------

### Quick Install GPM CLI

Source: https://docs.gpm.sh/getting-started/getting-started/installation

Use these commands for the fastest setup experience on your respective platform.

```bash
curl -fsSL https://gpm.sh/install.sh | sh
```

```powershell
iex ((New-Object System.Net.WebClient).DownloadString('https://gpm.sh/install.ps1'))
```

```cmd
powershell -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://gpm.sh/install.ps1'))"
```

--------------------------------

### Version Examples

Source: https://docs.gpm.sh/cli-reference/cli/utilities/version

Examples of different versioning states.

```bash
# Stable release
gpm version
# Version: v1.0.0

# Alpha release
gpm version
# Version: v1.1.0-alpha.1

# Beta release
gpm version
# Version: v1.1.0-beta.2

# Development build
gpm version
# Version: v1.1.0-dirty
```

--------------------------------

### Authentication Examples

Source: https://docs.gpm.sh/cli-reference/cli/authentication/login

Examples of logging into the default registry and a custom registry.

```bash
# Login to default registry
gpm login

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

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

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

--------------------------------

### Configuration Examples

Source: https://docs.gpm.sh/cli-reference/cli

Examples for managing GPM CLI configuration.

```APIDOC
## Configuration

### Set Configuration Value

```bash
# Set registry URL
gpm config set registry https://my.gpm.sh
```

### Get Configuration Value

```bash
# Get current configuration
gpm config get registry
```

### Show All Configuration

```bash
# Show all configuration
gpm config
```
```

--------------------------------

### Global Package Output Example

Source: https://docs.gpm.sh/cli-reference/cli/package-management/list

An example of the output when listing global packages. It shows the names and versions of globally installed packages.

```text
Global Packages
─────────────────────────────────────────
Registry: https://registry.gpm.sh
─────────────────────────────────────────

com.unity.analytics@2.1.0
com.unity.timeline@1.7.4
com.company.global-utils@1.0.0

─────────────────────────────────────────
3 packages installed globally
```

--------------------------------

### Display Version Examples

Source: https://docs.gpm.sh/cli-reference/cli/utilities

Examples of version output strings for different release types.

```bash
# Stable release
gpm version
# Version: v1.0.0

# Alpha release
gpm version
# Version: v1.1.0-alpha.1

# Development build
gpm version
# Version: v1.1.0-dirty
```

--------------------------------

### Unreal Engine CI/CD Integration Example

Source: https://docs.gpm.sh/multi-engine-support/engines/unreal

Example of integrating GPM into a CI/CD pipeline for Unreal Engine projects. This includes installing plugins, verifying the installation, and building the project.

```bash
# 1. Install plugins in CI (planned)
gpm install

# 2. Verify plugin installation (planned)
gpm list --json

# 3. Build Unreal Engine project (planned)
UnrealBuildTool.exe MyProject Development Win64 -Project="C:\Path\To\Project\Project.uproject"
```

--------------------------------

### Registry Package Version Specification

Source: https://docs.gpm.sh/cli-reference/cli/package-management/install

Examples of how to specify package versions when installing from a registry, including latest, specific, and version ranges.

```bash
# Latest version
gpm install package-name

# Specific version
gpm install package-name@1.2.3

# Version range
gpm install package-name@^1.0.0
gpm install package-name@~1.2.0
gpm install package-name@>=1.0.0
```

--------------------------------

### Unity Packages Examples

Source: https://docs.gpm.sh/package-guidelines/packages/naming

Examples of valid Unity package names.

```bash
com.unity.analytics
com.unity.textmeshpro
com.unity.timeline
com.unity.cinemachine
```

--------------------------------

### Third-Party SDKs Examples

Source: https://docs.gpm.sh/package-guidelines/packages/naming

Examples of valid third-party SDK package names.

```bash
com.gameanalytics.sdk
com.adjust.sdk
com.firebase.unity
com.facebook.unity
```

--------------------------------

### Install Package Globally

Source: https://docs.gpm.sh/cli-reference/cli/package-management/uninstall

Example of how to install a package globally using the gpm install command with the --global flag. This is often used for command-line tools or shared libraries.

```bash
gpm install com.unity.analytics --global
```

--------------------------------

### Dependency Tree Structure Example

Source: https://docs.gpm.sh/cli-reference/cli/package-management/list

An example output showing the dependency tree structure for installed packages. It details direct dependencies and their sub-dependencies.

```text
Installed Packages
─────────────────────────────────────────
Engine:   unity
Project:  /path/to/project
Registry: https://registry.gpm.sh
─────────────────────────────────────────

com.unity.analytics@2.1.0
├── com.unity.services.core@1.10.1
└── com.unity.services.analytics@1.0.0
    └── com.unity.services.core@1.10.1

com.unity.timeline@1.7.4
├── com.unity.ugui@1.0.0
└── com.unity.animation@6.0.0

─────────────────────────────────────────
2 packages installed
```

--------------------------------

### Package Naming Examples

Source: https://docs.gpm.sh/package-guidelines/packages/naming

Examples of recommended and discouraged package naming patterns.

```bash
# Good - Clear and consistent
com.company.game.analytics
com.company.game.ui
com.company.game.networking

# Good - Feature-based
com.company.analytics.core
com.company.analytics.events
com.company.analytics.dashboard

# Bad - Inconsistent
com.company.analytics
com.company.ui.package
com.company.networking-sdk
```

--------------------------------

### Basic gpm install Usage

Source: https://docs.gpm.sh/cli-reference/cli/package-management/install

Use this command to install packages. It can auto-detect the engine, install a single package, a specific version, or multiple packages.

```bash
gpm install [package[@version]...] [flags]
```

```bash
# Install from package.json (auto-detect engine)
gpm install

# Install single package
gpm install com.unity.textmeshpro

# Install specific version
gpm install com.unity.textmeshpro@2.1.0

# Install multiple packages
gpm install pkg1 pkg2 pkg3
```

--------------------------------

### Authentication Examples

Source: https://docs.gpm.sh/cli-reference/cli

Examples for authenticating with the GPM registry.

```APIDOC
## Authentication

### Login

```bash
# Login to registry
gpm login
```

### Who Am I

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

### Logout

```bash
# Logout from registry
gpm logout
```
```

--------------------------------

### Manage version channels

Source: https://docs.gpm.sh/cli-reference/cli/publishing/dist-tag

Example workflow for setting up and listing release channels.

```bash
# Set up release channels
gpm dist-tag add com.company.package alpha 1.0.0-alpha.1
gpm dist-tag add com.company.package beta 1.0.0-beta.1
gpm dist-tag add com.company.package stable 1.0.0

# List all channels
gpm dist-tag list com.company.package
```

--------------------------------

### Initialize and Customize Package

Source: https://docs.gpm.sh/cli-reference/cli/project/init

This example shows how to initialize a package and then manually customize the `package.json` and other files.

```bash
# Initialize and customize
gpm init --name com.company.mypackage
# Edit package.json
# Add custom files
# Customize README.md
```

--------------------------------

### Version Management

Source: https://docs.gpm.sh/cli-reference/cli/project

Example of initializing a package with a specific semantic version.

```bash
# Start with version 1.0.0
gpm init --name com.company.mypackage --version 1.0.0
```

--------------------------------

### Publishing Examples

Source: https://docs.gpm.sh/cli-reference/cli

Examples for publishing packages to the GPM registry.

```APIDOC
## Publishing

### Pack Package

```bash
# Pack package for publishing
gpm pack
```

### Publish Package

```bash
# Publish as public package
gpm publish --access=public

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

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

### Distribution Tags

```bash
# Manage distribution tags
gpm dist-tag add com.package beta 1.0.0
gpm dist-tag list com.package
```
```

--------------------------------

### Project Setup Workflow

Source: https://docs.gpm.sh/cli-reference/cli/project

Commands for configuring an existing project and managing dependencies.

```bash
# 1. Detect existing project
gpm detect /path/to/project

# 2. Install packages
gpm install com.unity.analytics

# 3. Add new packages
gpm add com.company.mypackage

# 4. List installed packages
gpm list
```

--------------------------------

### Install Packages for Unity Cloud Build

Source: https://docs.gpm.sh/multi-engine-support/engines/unity

Configure the registry and run 'gpm install' to prepare packages for Unity Cloud Build. Then, use the Unity Editor in batch mode to build.

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

```bash
gpm install
```

```bash
unity-editor -batchmode -quit -projectPath . -buildTarget StandaloneLinux64
```

--------------------------------

### Project Management Examples

Source: https://docs.gpm.sh/cli-reference/cli

Examples for project-related operations with GPM CLI.

```APIDOC
## Project Management

### Detect Engine

```bash
# Detect game engine project
gpm detect
```

### Initialize Package

```bash
# Initialize new package
gpm init --name com.company.package
```
```

--------------------------------

### Verify GPM Installation

Source: https://docs.gpm.sh/getting-started/getting-started/installation

Check the installed version and access help documentation to confirm successful installation.

```bash
gpm --version
```

```text
gpm version 1.0.0
```

```bash
gpm --help
```

--------------------------------

### Command Output Examples

Source: https://docs.gpm.sh/cli-reference/cli/authentication/whoami

Examples of the output returned by the command for different authentication states.

```text
User Information
─────────────────────────────────────────
Username: myusername
Registry: https://registry.gpm.sh
Status:   Authenticated
─────────────────────────────────────────
```

```text
Authentication Status
─────────────────────────────────────────
Registry: https://registry.gpm.sh
Status:   Not authenticated
─────────────────────────────────────────
Run 'gpm login' to authenticate
```

--------------------------------

### Package Management Examples

Source: https://docs.gpm.sh/cli-reference/cli

Examples demonstrating basic package management operations using the GPM CLI.

```APIDOC
## Basic Package Management

### Add Package

```bash
# Add a package to your project
gpm add com.unity.analytics

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

### Install Packages

```bash
# Install multiple packages
gpm install com.unity.textmeshpro com.unity.timeline
```

### Search Packages

```bash
# Search for packages
gpm search analytics --limit 10
```
```

--------------------------------

### Unity Manifest Update Example

Source: https://docs.gpm.sh/cli-reference/cli/package-management/update

Example of how the manifest.json file is updated after running the command.

```json
{
  "dependencies": {
    "com.unity.analytics": "2.2.0",  // Updated from 2.1.0
    "com.unity.timeline": "1.7.5"   // Updated from 1.7.4
  },
  "scopedRegistries": [
    {
      "name": "GPM",
      "url": "https://registry.gpm.sh",
      "scopes": ["com.unity"]
    }
  ]
}
```

--------------------------------

### Company Packages Examples

Source: https://docs.gpm.sh/package-guidelines/packages/naming

Examples of valid company-specific package names.

```bash
com.company.mygame.analytics
com.company.mygame.ui
com.company.mygame.networking
```

--------------------------------

### Development Setup Workflow

Source: https://docs.gpm.sh/cli-reference/cli/authentication

Standard sequence for setting up a development environment with a private registry.

```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
```

--------------------------------

### Unreal Engine Team Collaboration Workflow Example

Source: https://docs.gpm.sh/multi-engine-support/engines/unreal

Workflow for team collaboration on Unreal Engine projects using GPM. It covers installing plugins from an existing `.uproject`, adding new ones, updating, and committing changes to version control.

```bash
# 1. Install from existing .uproject (planned)
gpm install

# 2. Add new plugins (planned)
gpm add com.company.new-plugin

# 3. Update .uproject (planned)
gpm update

# 4. Commit changes (planned)
git add Project.uproject
git commit -m "Add new plugin dependencies"
```

--------------------------------

### Registry Management Configuration

Source: https://docs.gpm.sh/cli-reference/cli/configuration/config

Examples for setting different registry URLs.

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

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

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

--------------------------------

### Search Packages Example

Source: https://docs.gpm.sh/api-reference/api

An example of a request to search for packages, specifying search terms and pagination parameters.

```http
GET /-/v1/search?text=unity&size=10&from=0
```

--------------------------------

### Example Manifest.json

Source: https://docs.gpm.sh/multi-engine-support/engines/unity

Shows the structure of a manifest file managed by GPM.

```json
{
  "dependencies": {
    "com.unity.analytics": "2.1.0",
    "com.unity.textmeshpro": "3.0.6",
    "com.unity.timeline": "1.7.4"
  },
  "scopedRegistries": [
    {
      "name": "GPM",
      "url": "https://registry.gpm.sh",
      "scopes": ["com.unity"]
    }
  ]
}
```

--------------------------------

### List Installed Packages

Source: https://docs.gpm.sh/cli-reference/cli/package-management

View a list of all packages currently installed in the project.

```bash
# List installed packages: gpm list
```

--------------------------------

### Install Packages via CLI

Source: https://docs.gpm.sh/package-guidelines/packages

Commands for installing packages from the manifest or by specific name and version.

```bash
# Install from manifest
gpm install

# Install specific package
gpm install com.unity.analytics

# Install with version
gpm install com.unity.analytics@2.1.0
```

--------------------------------

### Manual Binary Installation

Source: https://docs.gpm.sh/getting-started/getting-started/installation

Steps to download, extract, and manually add the GPM binary to your system PATH.

```bash
# Download latest release
wget https://github.com/gpm-sh/gpm-cli/releases/latest/download/gpm-cli.tar.gz

# Extract
tar -xzf gpm-cli.tar.gz

# Install to system PATH
sudo mv gpm /usr/local/bin/

# Make executable
chmod +x /usr/local/bin/gpm
```

```powershell
# Download latest release
Invoke-WebRequest -Uri "https://github.com/gpm-sh/gpm-cli/releases/latest/download/gpm-cli.zip" -OutFile "gpm-cli.zip"

# Extract
Expand-Archive -Path "gpm-cli.zip" -DestinationPath "C:\Program Files\gpm"

# Add to PATH (requires admin)
$env:PATH += ";C:\Program Files\gpm"
```

--------------------------------

### Package Selection Best Practices

Source: https://docs.gpm.sh/cli-reference/cli/registry/info

Verify package integrity and ensure proper installation workflows.

```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 and Project Options for gpm Install

Source: https://docs.gpm.sh/cli-reference/cli/package-management/install

Specify a custom registry URL or the project directory when installing packages.

```bash
# Use custom registry
gpm install --registry https://homa.gpm.sh homa-analytics

# Specify project directory
gpm install --project-dir /path/to/project package-name
```

--------------------------------

### Installing Packages

Source: https://docs.gpm.sh/package-guidelines/packages/access-levels

Commands to install packages from different registries. Private packages require authentication via login.

```bash
# Install public package from global registry
gpm config set registry https://registry.gpm.sh
gpm install com.unity.analytics

# Install scoped package from tenant registry
gpm config set registry https://company.gpm.sh
gpm install com.company.analytics

# Install private package (requires authentication)
gpm config set registry https://company.gpm.sh
gpm login
gpm install com.company.proprietary
```

--------------------------------

### Install Godot Addons

Source: https://docs.gpm.sh/multi-engine-support/engines/godot

Commands to install addons based on project configuration or specific requirements.

```bash
# Install from project.godot (planned)
gpm install

# Install specific addon (planned)
gpm install com.company.godot-addon

# Install with version specification (planned)
gpm install com.company.godot-addon@1.0.0
```

--------------------------------

### Get Configuration Values

Source: https://docs.gpm.sh/cli-reference/cli/configuration/config

Retrieve specific or all configuration settings.

```bash
gpm config get <key>
```

```bash
# Get registry URL
gpm config get registry

# Get all configuration
gpm config

# Get specific setting
gpm config get engine.detect
```

```bash
# Single value
gpm config get registry
https://registry.gpm.sh

# All configuration
gpm config
{
  "registry": "https://registry.gpm.sh",
  "engine": {
    "detect": true,
    "unity": {
      "auto_scope": true
    }
  },
  "registry_timeout": 30,
  "telemetry": {
    "opt_in": false
  }
}
```

--------------------------------

### Basic Package Updates

Source: https://docs.gpm.sh/cli-reference/cli/package-management/update

Examples for updating all packages or specific ones.

```bash
# Update all packages
gpm update

# Update specific package
gpm update com.unity.analytics

# Update multiple packages
gpm update com.unity.analytics com.unity.timeline
```

--------------------------------

### Install Unity Packages

Source: https://docs.gpm.sh/multi-engine-support/engines/unity

Installs packages based on the project manifest or specific requirements.

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

# Install specific package
gpm install com.unity.analytics

# Install with version specification
gpm install com.unity.analytics@2.1.0
```

--------------------------------

### Local Package Installation

Source: https://docs.gpm.sh/cli-reference/cli/package-management/install

Install packages from a local directory using relative or absolute paths.

```bash
# From local directory
gpm install file:../local-package

# From absolute path
gpm install file:/path/to/package
```

--------------------------------

### GPM Package Naming Examples

Source: https://docs.gpm.sh/package-guidelines/packages

Provides concrete examples of GPM package names following the reverse-DNS convention for different types of packages.

```bash
com.unity.analytics - Unity Analytics package
com.gameanalytics.sdk - GameAnalytics SDK
com.company.mygame.ui - Company's UI package
```

--------------------------------

### Advanced gpm Installation Sources

Source: https://docs.gpm.sh/cli-reference/cli/package-management/install

Install packages directly from Git repositories or local directories, and manage dependencies.

```bash
# Install from Git
gpm install git+https://github.com/user/repo.git

# Install from local directory
gpm install file:../local-package

# Install and save to package.json
gpm install --save com.unity.analytics

# Install as dev dependency
gpm install --save-dev com.unity.test-framework
```

--------------------------------

### JSON output examples

Source: https://docs.gpm.sh/cli-reference/cli/registry/info

Retrieving package information formatted as JSON for programmatic use.

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

# Get specific version in JSON
gpm info com.unity.analytics --version 2.1.0 --json
```

--------------------------------

### Follow Addon Naming Conventions

Source: https://docs.gpm.sh/multi-engine-support/engines/godot

Examples of recommended reverse-DNS naming versus non-standard naming patterns.

```bash
# Good: Reverse-DNS naming
com.company.godot-addon
com.company.ui
com.thirdparty.analytics

# Avoid: Non-standard naming
@company/godot-addon
godot-addon-package
MyCompany.GodotAddon
```

--------------------------------

### Release management workflow

Source: https://docs.gpm.sh/cli-reference/cli/publishing/dist-tag

Example workflow for publishing, tagging, and promoting a package version.

```bash
# 1. Publish new version
gpm publish --access=scoped

# 2. Add beta tag
gpm dist-tag add com.company.package beta 1.0.0-beta.1

# 3. Test beta version
gpm install com.company.package@beta

# 4. Promote to stable
gpm dist-tag add com.company.package stable 1.0.0
gpm dist-tag add com.company.package latest 1.0.0
```

--------------------------------

### Manage package tags

Source: https://docs.gpm.sh/cli-reference/cli/publishing/dist-tag

Example workflow for listing, removing, and adding tags.

```bash
# List current tags
gpm dist-tag list com.company.package

# Remove old tags
gpm dist-tag remove com.company.package old-tag

# Add new tags
gpm dist-tag add com.company.package new-tag 1.0.0
```

--------------------------------

### Restore Packages

Source: https://docs.gpm.sh/cli-reference/cli/package-management/list

Run `gpm install` to install all packages defined in your project's configuration, typically after cloning a repository or sharing a package list.

```bash
gpm install
```

--------------------------------

### Package Naming Conventions

Source: https://docs.gpm.sh/cli-reference/cli/project

Examples of using reverse-DNS format and descriptive naming for packages.

```bash
# Use reverse-DNS format
gpm init --name com.company.mypackage

# Use descriptive names
gpm init --name com.company.game-analytics
gpm init --name com.company.networking-utils
```

--------------------------------

### Initialize Development Environment

Source: https://docs.gpm.sh/cli-reference/cli/package-management

Standard sequence for setting up a new project and adding initial dependencies.

```bash
# 1. Initialize project
gpm init

# 2. Add essential packages
gpm add com.unity.analytics
gpm add com.unity.textmeshpro

# 3. Add third-party SDKs
gpm add com.gameanalytics.sdk
gpm add com.adjust.sdk

# 4. List installed packages
gpm list
```

--------------------------------

### Login Output Examples

Source: https://docs.gpm.sh/cli-reference/cli/authentication/login

Expected output for successful and failed authentication attempts.

```text
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
```

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

--------------------------------

### CI/CD Authentication Setup

Source: https://docs.gpm.sh/cli-reference/cli/authentication

Configure authentication for non-interactive CI/CD environments using environment variables.

```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
```

--------------------------------

### Configuration JSON Output

Source: https://docs.gpm.sh/getting-started/getting-started/configuration

Example of the JSON structure returned by the configuration command.

```json
{
  "registry": "https://registry.gpm.sh",
  "registry_timeout": 30,
  "engine": {
    "detect": true,
    "unity": {
      "auto_scope": true
    }
  },
  "telemetry": {
    "opt_in": false
  }
}
```

--------------------------------

### Install Packages with GPM

Source: https://docs.gpm.sh/cli-reference/cli/examples

Use 'gpm install' to install packages. This can be used to install all packages listed in a package.json file, or specific 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
```

--------------------------------

### Best practices for tag naming

Source: https://docs.gpm.sh/cli-reference/cli/publishing/dist-tag

Example of using semantic tag names.

```bash
# Use semantic tag names
gpm dist-tag add com.company.package stable 1.0.0
gpm dist-tag add com.company.package beta 1.1.0-beta.1
```

--------------------------------

### Configure Global Packages

Source: https://docs.gpm.sh/cli-reference/cli/package-management

Commands for installing and listing packages at the global level.

```bash
# Install globally
gpm install com.unity.analytics --global

# List global packages
gpm list --global
```

--------------------------------

### CI/CD Integration

Source: https://docs.gpm.sh/multi-engine-support/engines/unity

Automated steps for installing dependencies and building in CI environments.

```bash
# 1. Install dependencies in CI
gpm install

# 2. Verify package installation
gpm list --json

# 3. Build Unity project
unity-editor -batchmode -quit -projectPath . -buildTarget StandaloneLinux64
```

--------------------------------

### Publish and Install Public Packages

Source: https://docs.gpm.sh/package-guidelines/packages/registry-resolution

Commands for managing public packages using the global registry.

```bash
# Publish public package (requires global registry)
gpm config set registry https://registry.gpm.sh
gpm login
gpm publish --access=public

# Install public package (works from any registry)
gpm install com.unity.analytics
```

--------------------------------

### Basic search examples

Source: https://docs.gpm.sh/cli-reference/cli/registry/search

Common search patterns including limits and detailed output.

```bash
# Search for packages
gpm search unity

# Search with limit
gpm search analytics --limit 20

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

--------------------------------

### Researching Packages with GPM

Source: https://docs.gpm.sh/cli-reference/cli/registry/info

Use these commands to inspect package details and verify compatibility before installation.

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

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

--------------------------------

### Create Basic Package

Source: https://docs.gpm.sh/cli-reference/cli/project/init

Example of creating a basic package using `gpm init` with the `--name` and `--yes` flags.

```bash
# Create basic package
gpm init --name com.company.basic --yes
```

--------------------------------

### Initialize Packages with Naming Conventions

Source: https://docs.gpm.sh/cli-reference/cli/project/init

Use reverse-DNS format for package names to ensure consistency and avoid conflicts.

```bash
# Use descriptive package names
gpm init --name com.company.analytics-sdk

# Use consistent naming convention
gpm init --name com.company.ui-framework
gpm init --name com.company.networking-utils
```

--------------------------------

### Successful Package Installation Output

Source: https://docs.gpm.sh/cli-reference/cli/package-management/install

This output indicates a successful installation of a package using the GPM CLI. It shows the detected engine, version, and confirmation of successful installation.

```text
Multi-Engine Package Installation
────────────────────────────────────
Detected Engine: Unity
Confidence:      High
Version:         2022.3.15f1
Project Path:    /path/to/project
────────────────────────────────────
Installing:      com.unity.textmeshpro@3.0.6
Registry:        https://registry.gpm.sh
Package installed successfully
```

--------------------------------

### Project.godot Configuration

Source: https://docs.gpm.sh/multi-engine-support/engines/godot

Example of how GPM will automatically update the project.godot file with addon references.

```ini
[application]

config/name="My Godot Project"
run/main_scene="res://Main.tscn"

[addons]

com.company.godot-addon="res://addons/com.company.godot-addon/plugin.cfg"
com.company.ui="res://addons/com.company.ui/plugin.cfg"
```

--------------------------------

### Verify GPM Installation

Source: https://docs.gpm.sh/getting-started/getting-started

Check the installed version of the GPM CLI.

```bash
gpm --version
```

--------------------------------

### Manage Configuration Best Practices

Source: https://docs.gpm.sh/cli-reference/cli/configuration/config

Recommended workflows for managing configuration files and version control.

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

# Use config file for local development
gpm config set registry https://dev.gpm.sh

# Document configuration changes
git add ~/.config/gpm/config.json
git commit -m "Update GPM configuration"
```

--------------------------------

### Initialize a New UPM Package with Custom Values

Source: https://docs.gpm.sh/cli-reference/cli/project/init

Initialize a package with specific custom values for name, version, description, license, and minimum Unity version.

```bash
# Initialize with custom values
gpm init --name com.company.mypackage --version 1.0.0 --description "My package" --license MIT --unity 2022.3
```

--------------------------------

### Initialize GPM Package with Details

Source: https://docs.gpm.sh/package-guidelines/packages

Command to create a new GPM package, specifying its name, version, and description.

```bash
# Create with specific values
gpm init --name com.company.mypackage --version 1.0.0 --description "My package"
```

--------------------------------

### Publish and Install Private Packages

Source: https://docs.gpm.sh/package-guidelines/packages/registry-resolution

Commands for managing private packages requiring authentication and a tenant registry.

```bash
# Publish private package (requires tenant registry + auth)
gpm config set registry https://company.gpm.sh
gpm login
gpm publish --access=private

# Install private package (requires tenant registry + auth)
gpm config set registry https://company.gpm.sh
gpm login
gpm install com.company.private-package
```

--------------------------------

### Install GPM via Package Managers

Source: https://docs.gpm.sh/getting-started/getting-started/installation

Standard package manager commands for macOS, Windows, and Linux environments.

```bash
brew install gpm-sh/gpm/gpm
```

```powershell
scoop bucket add gpm https://github.com/gpm-sh/scoop-bucket
scoop install gpm
```

```bash
sudo snap install gpm --classic
```

--------------------------------

### Validate Configuration Values

Source: https://docs.gpm.sh/cli-reference/cli/configuration/config

Examples of valid and invalid configuration inputs and their corresponding error messages.

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

# Invalid registry URL
gpm config set registry not-a-url
Error: invalid registry URL: not-a-url

# Valid timeout
gpm config set registry_timeout 60

# Invalid timeout
gpm config set registry_timeout not-a-number
Error: invalid timeout value: not-a-number
```

--------------------------------

### Reinstall GPM

Source: https://docs.gpm.sh/troubleshooting/troubleshooting

Download and install the GPM CLI using the official installation script.

```bash
curl -fsSL https://gpm.sh/install.sh | sh
```

--------------------------------

### Example package.json Structure

Source: https://docs.gpm.sh/cli-reference/cli/publishing/publish

A valid package.json file is required for publishing. Ensure 'name', 'version', and 'description' fields are present.

```json
{
  "name": "com.company.mypackage",
  "version": "1.0.0",
  "description": "My awesome package",
  "author": "Company Name",
  "license": "MIT",
  "keywords": ["unity", "game", "analytics"],
  "repository": {
    "type": "git",
    "url": "https://github.com/company/mypackage"
  },
  "unity": "2022.3"
}
```

--------------------------------

### Initialize New Packages

Source: https://docs.gpm.sh/cli-reference/cli/project

Commands for creating new package structures with specific configurations.

```bash
# Initialize new package
gpm init

# Initialize with specific values
gpm init --name com.company.mypackage --description "My package"

# Initialize with all defaults
gpm init --yes
```

--------------------------------

### Manually Install GPM

Source: https://docs.gpm.sh/getting-started/getting-started

Download and install the GPM binary manually for Unix-based systems.

```bash
# Example for macOS/Linux
wget https://github.com/gpm-sh/gpm-cli/releases/latest/download/gpm-cli.tar.gz
tar -xzf gpm-cli.tar.gz
sudo mv gpm /usr/local/bin/
```

--------------------------------

### Project Organization Best Practices

Source: https://docs.gpm.sh/cli-reference/cli/project

Recommended directory structure and naming conventions for projects.

```bash
# Organize projects by engine
mkdir -p /workspace/unity-projects
mkdir -p /workspace/godot-projects
mkdir -p /workspace/unreal-projects

# Use clear naming conventions
gpm init --name com.company.analytics-sdk
gpm init --name com.company.ui-framework
```

--------------------------------

### Verify Package Installation Count in CI/CD

Source: https://docs.gpm.sh/cli-reference/cli/package-management/list

In CI/CD environments, use `gpm list --json | jq '.packages.production | length'` to verify the number of production packages installed. This requires `jq` to be installed.

```bash
gpm list --json | jq '.packages.production | length'
```

--------------------------------

### Best Practices for Versioning

Source: https://docs.gpm.sh/cli-reference/cli/utilities/version

Recommended patterns for reporting and compatibility checks.

```bash
# Always check version before reporting issues
gpm version

# Include version in bug reports
gpm version --json > version-info.json

# Check version compatibility
gpm version --json | jq '.version | startswith("v1.")'

# Verify minimum version
gpm version --json | jq '.version | split(".") | .[0] | tonumber'

# Document version in scripts
VERSION=$(gpm version --json | jq -r '.version')
echo "Using GPM version: $VERSION"
```

--------------------------------

### Development Workflow: Pack and Publish

Source: https://docs.gpm.sh/cli-reference/cli/project

Pack the project for distribution and publish it with scoped access.

```bash
gpm pack
```

```bash
gpm publish --access=scoped
```

--------------------------------

### Install GPM CLI

Source: https://docs.gpm.sh/getting-started/getting-started

Use these commands to install the GPM CLI on macOS, Linux, or Windows systems.

```bash
# macOS/Linux
curl -fsSL https://gpm.sh/install.sh | sh

# Windows (PowerShell)
iex ((New-Object System.Net.WebClient).DownloadString('https://gpm.sh/install.ps1'))
```

--------------------------------

### Initial GPM Configuration

Source: https://docs.gpm.sh/getting-started/getting-started/installation

Set the registry URL and authenticate your session to begin using GPM.

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

```bash
gpm login
```

```bash
gpm config
```

--------------------------------

### Engine-Specific Installation with gpm

Source: https://docs.gpm.sh/cli-reference/cli/package-management/install

Force the installation of a package for a specific game engine using the respective flag.

```bash
# Force Unity engine
gpm install --unity com.unity.textmeshpro

# Force Unreal engine
gpm install --unreal adjust-sdk

# Force Godot engine
gpm install --godot godot-analytics

# Force Cocos Creator engine
gpm install --cocos cocos-analytics
```

--------------------------------

### Initialize a New Package with Specific Unity Version

Source: https://docs.gpm.sh/multi-engine-support/engines/unity

Use 'gpm init' with the '--name' and '--unity' flags to initialize a new package with a specified name and minimum Unity version compatibility.

```bash
gpm init --name com.company.package --unity 2022.3
```

--------------------------------

### Dry Run Output Example

Source: https://docs.gpm.sh/cli-reference/cli/package-management/update

Example output showing the result of a dry run update operation.

```text
Update Preview
─────────────────────────────────────────
Engine:   unity
Project:  /path/to/project
Registry: https://registry.gpm.sh
─────────────────────────────────────────

Would Update:
  com.unity.analytics: 2.1.0 → 2.2.0
  com.unity.timeline:  1.7.4 → 1.7.5

Would Not Update:
  com.unity.textmeshpro: 3.0.6 (latest)

─────────────────────────────────────────
Run without --dry-run to apply updates
```

--------------------------------

### Manage Package Versions

Source: https://docs.gpm.sh/cli-reference/cli/project/init

Initialize packages with a starting version and use semantic versioning commands to increment releases.

```bash
# Start with version 1.0.0
gpm init --name com.company.mypackage --version 1.0.0

# Use semantic versioning
gpm version patch  # 1.0.0 → 1.0.1
gpm version minor  # 1.0.0 → 1.1.0
gpm version major  # 1.0.0 → 2.0.0
```

--------------------------------

### Git Package Installation

Source: https://docs.gpm.sh/cli-reference/cli/package-management/install

Install packages directly from Git repositories, specifying branches, tags, or the default branch.

```bash
# From main branch
gpm install git+https://github.com/user/repo.git

# From specific branch
gpm install git+https://github.com/user/repo.git#develop

# From specific tag
gpm install git+https://github.com/user/repo.git#v1.0.0
```

--------------------------------

### Install GPM CLI

Source: https://docs.gpm.sh/

Use these commands to install the GPM CLI on macOS/Linux or Windows. Ensure you have curl or PowerShell available.

```bash
# macOS/Linux
curl -fsSL https://gpm.sh/install.sh | sh
```

```powershell
# Windows (PowerShell)
iex ((New-Object System.Net.WebClient).DownloadString('https://gpm.sh/install.ps1'))
```

--------------------------------

### Initialize Version Control for Packages

Source: https://docs.gpm.sh/cli-reference/cli/project/init

Set up a Git repository for a new package to track changes and manage remote synchronization.

```bash
# Initialize package
gpm init --name com.company.mypackage

# Initialize git repository
git init
git add .
git commit -m "Initial package structure"

# Add remote repository
git remote add origin https://github.com/company/mypackage.git
git push -u origin main
```

--------------------------------

### Get Detailed Error Information with GPM

Source: https://docs.gpm.sh/multi-engine-support/engines/unity

Use the '--verbose' flag with GPM commands to get detailed error information for debugging.

```bash
gpm add com.unity.analytics --verbose
```

--------------------------------

### Initialize New Package

Source: https://docs.gpm.sh/cli-reference/cli/project/detect

Detect an existing project with 'gpm detect'. Subsequently, initialize a new package within that project using 'gpm init' with a specified package name.

```bash
# Detect existing project
gpm detect

# Initialize new package in project
gpm init --name com.company.mypackage
```

--------------------------------

### Development Workflow: Detect and Initialize

Source: https://docs.gpm.sh/cli-reference/cli/project

Check the project type and initialize a new package with a specified name during development.

```bash
gpm detect
```

```bash
gpm init --name com.company.mypackage
```

--------------------------------

### Install Unreal Engine Plugins

Source: https://docs.gpm.sh/multi-engine-support/engines/unreal

Install plugins for your Unreal Engine project. This can be done for the entire project based on the `.uproject` file, or for specific plugins with optional versioning.

```bash
# Install from .uproject (planned)
gpm install

# Install specific plugin (planned)
gpm install com.company.unreal-plugin

# Install with version specification (planned)
gpm install com.company.unreal-plugin@1.0.0
```

--------------------------------

### Get GPM Search Results in JSON

Source: https://docs.gpm.sh/cli-reference/cli/examples

Use the '--json' flag with 'gpm search' to get structured JSON output, which is useful for scripting and automation. The output includes success status, query details, total results, and a list of found packages.

```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"
    }
  ]
}
```

--------------------------------

### JSON Output Format

Source: https://docs.gpm.sh/cli-reference/cli/utilities/version

Example of the machine-readable JSON output.

```json
{
  "version": "v0.1.0-alpha.7-dirty",
  "commit": "754da3a",
  "built": "2025-09-14_09:39:23",
  "go_version": "go1.25.0",
  "platform": "darwin/arm64",
  "arch": "arm64",
  "os": "darwin"
}
```

--------------------------------

### Timeout Settings

Source: https://docs.gpm.sh/cli-reference/cli/configuration/config

Examples for adjusting registry request timeouts.

```bash
# Set registry timeout
gpm config set registry_timeout 60

# Set longer timeout for slow networks
gpm config set registry_timeout 120
```

--------------------------------

### Global Package Updates

Source: https://docs.gpm.sh/cli-reference/cli/package-management/update

Update packages installed in the global scope.

```bash
# Update global packages
gpm update --global

# Update specific global package
gpm update com.unity.analytics --global
```

--------------------------------

### Package information retrieval examples

Source: https://docs.gpm.sh/cli-reference/cli/registry/info

Common patterns for querying package details, including specific versions and verbose output.

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

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

# Show detailed information
gpm info com.unity.analytics --verbose
```

--------------------------------

### Shared Configuration Template

Source: https://docs.gpm.sh/getting-started/getting-started/configuration

Example JSON template for team-wide configuration.

```json
{
  "registry": "https://company.gpm.sh",
  "registry_timeout": 60,
  "engine": {
    "detect": true,
    "unity": {
      "auto_scope": true
    }
  },
  "telemetry": {
    "opt_in": false
  }
}
```

--------------------------------

### Human Readable Output

Source: https://docs.gpm.sh/cli-reference/cli/utilities/version

Example of the default console output format.

```text
GPM CLI
─────────────────────────────────────────
Version: v0.1.0-alpha.7-dirty
Commit: 754da3a
Built: 2025-09-14_09:39:23
Go Version: go1.25.0
Platform: darwin/arm64
─────────────────────────────────────────
```

--------------------------------

### Initialize and Pack Package

Source: https://docs.gpm.sh/cli-reference/cli/publishing

Prepare a package for publishing by first initializing it and then packing it into a tarball. The `gpm pack` command creates the distributable file.

```bash
gpm init

gpm pack

gpm publish --access=scoped
```

--------------------------------

### Engine Configuration

Source: https://docs.gpm.sh/cli-reference/cli/configuration/config

Examples for toggling engine detection and Unity auto-scoping.

```bash
# Enable engine detection
gpm config set engine.detect true

# Disable engine detection
gpm config set engine.detect false

# Configure Unity auto-scoping
gpm config set engine.unity.auto_scope true
```

--------------------------------

### Unreal Engine Development Workflow Example

Source: https://docs.gpm.sh/multi-engine-support/engines/unreal

A typical development workflow using GPM for Unreal Engine projects. This includes navigating to the project, detecting it, adding essential plugins, listing them, and updating regularly.

```bash
# 1. Navigate to Unreal Engine project
cd /path/to/unreal/project

# 2. Detect project (automatic)
gpm detect

# 3. Add essential plugins (planned)
gpm add com.company.ui
gpm add com.company.analytics
gpm add com.company.networking

# 4. List installed plugins (planned)
gpm list

# 5. Update plugins regularly (planned)
gpm update
```

--------------------------------

### Execute Package Publishing Workflow

Source: https://docs.gpm.sh/package-guidelines/packages

Standard command-line sequence for initializing, packing, and publishing a package to the registry.

```bash
# 1. Initialize
gpm init --name com.company.mypackage

# 2. Develop (add code, assets, etc.)

# 3. Pack
gpm pack

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

--------------------------------

### Reload Shell Configuration

Source: https://docs.gpm.sh/troubleshooting/troubleshooting

Apply changes to your shell configuration files after installation.

```bash
source ~/.bashrc  # Linux
source ~/.zshrc   # macOS with Zsh
```

--------------------------------

### Configure Multi-Registry Setup with Environment Variables

Source: https://docs.gpm.sh/cli-reference/cli/configuration

Use environment variables to manage different registries. This allows for dynamic switching between registries based on the environment.

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

```bash
# Override for specific commands
gpm search package --registry https://registry.gpm.sh
```

```bash
gpm publish --registry https://company.gpm.sh
```

--------------------------------

### Basic Package Management Commands

Source: https://docs.gpm.sh/cli-reference/cli

Use these commands to add, install, and search for packages within your game project.

```bash
# Add a package to your project
gpm add com.unity.analytics

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

# Install multiple packages
gpm install com.unity.textmeshpro com.unity.timeline

# Search for packages
gpm search analytics --limit 10
```

--------------------------------

### Update Unity Packages

Source: https://docs.gpm.sh/multi-engine-support/engines/unity

Updates installed packages, with support for dry runs.

```bash
# Update all packages
gpm update

# Update specific package
gpm update com.unity.analytics

# Dry run to see what would be updated
gpm update --dry-run
```

--------------------------------

### Check GPM version

Source: https://docs.gpm.sh/cli-reference/cli

Displays the currently installed version of the GPM CLI.

```bash
gpm version
```

--------------------------------

### Login via API

Source: https://docs.gpm.sh/api-reference/api

Use this command to authenticate with the registry and obtain an authentication token. Ensure you replace 'username' and 'password' with your actual credentials.

```bash
curl -X PUT https://registry.gpm.sh/-/user/org.couchdb.user:username \
  -H "Content-Type: application/json" \
  -d '{"name": "username", "password": "password", "email": "user@example.com"}'
```

--------------------------------

### Team Collaboration Workflow

Source: https://docs.gpm.sh/getting-started/getting-started

Commands for installing dependencies and sharing changes with a team.

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

# 2. Add new dependencies
gpm add com.company.newpackage

# 3. Share with team
git add Packages/manifest.json
git commit -m "Add new package dependency"
```

--------------------------------

### Publishing Packages

Source: https://docs.gpm.sh/getting-started/getting-started

Steps to pack and publish a package to the registry.

```bash
# 1. Create package with package.json
# 2. Test locally
gpm pack

# 3. Publish to registry
gpm publish --access=scoped
```

--------------------------------

### Manage Global Packages

Source: https://docs.gpm.sh/cli-reference/cli/package-management/update

Commands for updating and listing packages installed globally.

```bash
# Update all global packages
gpm update --global

# Update specific global package
gpm update com.unity.analytics --global

# List global packages
gpm list --global
```

--------------------------------

### Publish Unity Packages

Source: https://docs.gpm.sh/multi-engine-support/engines/unity

Commands for initializing, packing, and publishing custom Unity packages.

```bash
# Initialize new Unity package
gpm init --name com.company.mypackage

# Pack package
gpm pack

# Publish to registry
gpm publish --access=scoped
```

--------------------------------

### Human-readable output format

Source: https://docs.gpm.sh/cli-reference/cli/registry/info

Example of the default console output for the info command.

```text
Package Information
─────────────────────────────────────────
Name: com.unity.analytics
Description: Analytics and insights for Unity games
Dist-tags: latest: 2.1.0

Latest Version: 2.1.0
Author: Unity Technologies <support@unity3d.com>
Keywords: unity, analytics, insights
Unity Version: 2021.3

Distribution:
  Tarball: https://cdn.gpm.sh/tarballs/com.unity.analytics/2.1.0.tgz
  Integrity: sha512-rjzUCACnBKOYRtn2Ttv67MRXFDNLsL1FSTgzyp4m6IYGErjRyYFJBO0O9cfjFrB1j79WvCR072HSe4a31ug1tQ==

Dependencies:
  com.unity.services.core@1.10.1
  com.unity.services.analytics@1.0.0

─────────────────────────────────────────
```

--------------------------------

### Remove a distribution tag

Source: https://docs.gpm.sh/cli-reference/cli/publishing/dist-tag

Syntax and examples for removing a distribution tag from a package.

```bash
gpm dist-tag remove <package> <tag>
```

```bash
# Remove beta tag
gpm dist-tag remove com.company.package beta

# Remove alpha tag
gpm dist-tag remove com.company.package alpha
```

--------------------------------

### Version Range Updates

Source: https://docs.gpm.sh/cli-reference/cli/package-management/update

Examples of how semver ranges affect update behavior.

```bash
# Update within current major version
gpm update com.unity.analytics  # 2.1.0 → 2.2.0

# Update to latest major version
gpm update com.unity.analytics  # 2.1.0 → 3.0.0 (if available)
```