# gpm config View and modify GPM configuration settings. ## Usage ```bash gpm config [flags] gpm config [command] ``` ## Commands | Command | Description | Usage | | ----------------------------------- | ------------------------- | ------------------------------ | | [`gpm config get`](#gpm-config-get) | Get a configuration value | `gpm config get ` | | [`gpm config set`](#gpm-config-set) | Set a configuration value | `gpm config set ` | ## Description The `gpm config` command manages GPM configuration settings stored in the local configuration file. Configuration values control registry URLs, engine settings, and other CLI behavior. ### Configuration File Locations * **macOS**: `~/Library/Application Support/gpm/config.json` * **Linux**: `~/.config/gpm/config.json` * **Windows**: `%AppData%\gpm\config.json` ### Configuration Precedence 1. **Command Line Flags**: Highest priority 2. **Environment Variables**: `GPM_*` variables 3. **Configuration File**: Local config file 4. **Default Values**: Built-in defaults ## gpm config get Get the value of a configuration key. ### Usage ```bash gpm config get ``` ### Arguments * `` - Configuration key to retrieve ### Examples ```bash # Get registry URL gpm config get registry # Get all configuration gpm config # Get specific setting gpm config get engine.detect ``` ### Output ```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 } } ``` ## gpm config set Set a configuration key to a specific value. ### Usage ```bash gpm config set ``` ### Arguments * `` - Configuration key to set * `` - Value to set ### Examples ```bash # Set registry URL gpm config set registry https://company.gpm.sh # Set engine detection gpm config set engine.detect false # Set timeout gpm config set registry_timeout 60 ``` ### Output ```bash # Successful set gpm config set registry https://company.gpm.sh Configuration updated: registry = https://company.gpm.sh # Error gpm config set invalid.key value Error: invalid configuration key: invalid.key ``` ## 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 Configuration ### Registry Management ```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 ``` ### Engine Configuration ```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 ``` ### Timeout Settings ```bash # Set registry timeout gpm config set registry_timeout 60 # Set longer timeout for slow networks gpm config set registry_timeout 120 ``` ## 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 Examples ### 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 Validation ### Key Validation GPM validates configuration keys: * **Valid keys**: Must match known configuration schema * **Invalid keys**: Rejected with error message * **Type validation**: Values must match expected types ### Value Validation ```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 ``` ## Error Handling ### Common Errors * **Invalid key**: `invalid configuration key: unknown.key` * **Invalid value**: `invalid value for key: expected type` * **File access error**: `failed to write configuration file` * **Permission denied**: `permission denied: cannot write config file` ### Troubleshooting 1. **Invalid key**: Check available configuration keys 2. **Invalid value**: Verify value format and type 3. **File access error**: Check file permissions and disk space 4. **Permission denied**: Run with appropriate permissions ## 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 ``` ## Related Commands * [`gpm login`](/cli-reference/cli/authentication/login.md) - Authentication management * [`gpm whoami`](/cli-reference/cli/authentication/whoami.md) - User information * [`gpm search`](/cli-reference/cli/registry/search.md) - Package search ## See Also * [Configuration Overview](/cli-reference/cli/configuration.md) * [Registry Resolution](https://github.com/gpm-sh/docs/blob/main/packages/registry-resolution.md) * [Environment Variables](https://github.com/gpm-sh/docs/blob/main/troubleshooting/common-issues.md#environment) --- # 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/config.md?ask= ``` 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.