# Configuration

Manage GPM configuration settings for registry URLs, engine detection, and CLI behavior.

## Overview

GPM provides comprehensive configuration management for customizing registry URLs, engine detection behavior, and other CLI settings. Configuration supports multiple sources with clear precedence rules.

## Commands

| Command                                                    | Description                   | Usage                  |
| ---------------------------------------------------------- | ----------------------------- | ---------------------- |
| [`gpm config`](/cli-reference/cli/configuration/config.md) | View and modify configuration | `gpm config [command]` |

## Quick Start

### Basic Configuration

```bash
# View current configuration
gpm config

# Get specific setting
gpm config get registry

# Set configuration value
gpm config set registry https://company.gpm.sh
```

### Common Settings

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

# Set timeout
gpm config set registry_timeout 60

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

## Configuration Sources

### Precedence Order

1. **Command Line Flags**: Highest priority
2. **Environment Variables**: `GPM_*` variables
3. **Configuration File**: Local config file
4. **Default Values**: Built-in defaults

### Configuration File Locations

* **macOS**: `~/Library/Application Support/gpm/config.json`
* **Linux**: `~/.config/gpm/config.json`
* **Windows**: `%AppData%\gpm\config.json`

## Registry Configuration

### Registry URLs

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

# Tenant registry
gpm config set registry https://company.gpm.sh

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

### Registry Timeout

```bash
# Set timeout in seconds
gpm config set registry_timeout 60

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

## Engine Configuration

### Engine Detection

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

# Disable automatic engine detection
gpm config set engine.detect false
```

### Unity Configuration

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

# Disable Unity auto-scoping
gpm config set engine.unity.auto_scope false
```

## Environment Variables

### GPM\_\* Variables

Environment variables override configuration file values:

```bash
# Set registry via environment
export GPM_REGISTRY=https://company.gpm.sh

# Set timeout via environment
export GPM_REGISTRY_TIMEOUT=60

# Set engine detection via environment
export GPM_ENGINE_DETECT=false
```

### Environment Variable Mapping

| Environment Variable   | Configuration Key  | Description      |
| ---------------------- | ------------------ | ---------------- |
| `GPM_REGISTRY`         | `registry`         | Registry URL     |
| `GPM_REGISTRY_TIMEOUT` | `registry_timeout` | Registry timeout |
| `GPM_ENGINE_DETECT`    | `engine.detect`    | Engine detection |
| `GPM_TELEMETRY_OPT_IN` | `telemetry.opt_in` | Telemetry opt-in |

## Configuration Keys

### Registry Settings

| Key                | Description                        | Default                   | Example                  |
| ------------------ | ---------------------------------- | ------------------------- | ------------------------ |
| `registry`         | Default registry URL               | `https://registry.gpm.sh` | `https://company.gpm.sh` |
| `registry_timeout` | Registry request timeout (seconds) | `30`                      | `60`                     |

### Engine Settings

| Key                       | Description                            | Default | Example |
| ------------------------- | -------------------------------------- | ------- | ------- |
| `engine.detect`           | Enable automatic engine detection      | `true`  | `false` |
| `engine.unity.auto_scope` | Auto-configure Unity scoped registries | `true`  | `false` |

### Telemetry Settings

| Key                | Description                 | Default | Example |
| ------------------ | --------------------------- | ------- | ------- |
| `telemetry.opt_in` | Enable telemetry collection | `false` | `true`  |

## Common Workflows

### Development Setup

```bash
# Set up development environment
gpm config set registry https://dev.gpm.sh
gpm config set registry_timeout 30
gpm config set engine.detect true
gpm config set telemetry.opt_in false
```

### Production Setup

```bash
# Set up production environment
gpm config set registry https://registry.gpm.sh
gpm config set registry_timeout 60
gpm config set engine.detect true
gpm config set telemetry.opt_in true
```

### CI/CD Setup

```bash
# Set up CI/CD environment
export GPM_REGISTRY=https://company.gpm.sh
export GPM_REGISTRY_TIMEOUT=120
export GPM_ENGINE_DETECT=false
export GPM_TELEMETRY_OPT_IN=false
```

## Configuration Examples

### Team Configuration

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

# Set appropriate timeout
gpm config set registry_timeout 60

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

### Multi-Registry Setup

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

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

### Network Configuration

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

# Use proxy settings
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
```

## Best Practices

### Configuration Management

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

### Security Considerations

```bash
# Never commit sensitive configuration
echo "config.json" >> .gitignore

# Use environment variables for secrets
export GPM_REGISTRY=https://user:password@company.gpm.sh

# Use config file for non-sensitive settings
gpm config set registry_timeout 60
```

### Team Collaboration

```bash
# Share configuration templates
cat > gpm-config-template.json << EOF
{
  "registry": "https://company.gpm.sh",
  "registry_timeout": 60,
  "engine": {
    "detect": true,
    "unity": {
      "auto_scope": true
    }
  },
  "telemetry": {
    "opt_in": false
  }
}
EOF
```

## Troubleshooting

### Common Issues

* **Configuration not applied**: Check precedence order
* **Invalid configuration**: Verify key names and values
* **File access error**: Check permissions and disk space
* **Environment variables not working**: Verify variable names

### Debug Steps

1. **Check current configuration**: `gpm config`
2. **Verify environment variables**: `env | grep GPM_`
3. **Check configuration file**: `cat ~/.config/gpm/config.json`
4. **Test configuration**: `gpm search test`

## Related Commands

* [Authentication](/cli-reference/cli/authentication.md) - User authentication
* [Registry Operations](/cli-reference/cli/registry.md) - Package search and info
* [Package Management](/cli-reference/cli/package-management.md) - Package installation

## See Also

* [Registry Resolution](https://github.com/gpm-sh/docs/blob/main/packages/registry-resolution.md) - Registry configuration details
* [Environment Variables](https://github.com/gpm-sh/docs/blob/main/troubleshooting/common-issues.md#environment) - Environment variable usage
* [Troubleshooting](https://github.com/gpm-sh/docs/blob/main/troubleshooting/README.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/configuration.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.