# Utility Commands

Essential utility commands for GPM CLI management and system information.

## Overview

GPM provides utility commands for version information, system diagnostics, and CLI management. These commands help users understand their GPM installation and troubleshoot issues.

## Commands

| Command                                                  | Description          | Usage         |
| -------------------------------------------------------- | -------------------- | ------------- |
| [`gpm version`](/cli-reference/cli/utilities/version.md) | Show GPM CLI version | `gpm version` |

## Quick Start

### Version Information

```bash
# Show version information
gpm version

# Show version in JSON format
gpm version --json
```

### System Information

```bash
# Get system details
gpm version --json | jq '.platform'

# Check Go version
gpm version --json | jq '.go_version'
```

## Version Management

### Version Information

The `gpm version` command provides comprehensive version information:

* **Version Number**: Semantic versioning format
* **Build Details**: Commit hash and build timestamp
* **Go Version**: Go compiler version used
* **Platform**: Operating system and architecture

### Version Examples

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

## Platform Support

### Supported Platforms

GPM supports multiple platforms:

* **macOS**: `darwin/amd64`, `darwin/arm64`
* **Linux**: `linux/amd64`, `linux/arm64`
* **Windows**: `windows/amd64`, `windows/arm64`

### Platform Detection

```bash
# Check current platform
gpm version --json | jq '.platform'

# Check architecture
gpm version --json | jq '.arch'

# Check operating system
gpm version --json | jq '.os'
```

## Use Cases

### Version Checking

```bash
# Check GPM version
gpm version

# Verify minimum version
gpm version --json | jq '.version'
```

### System Diagnostics

```bash
# Get system information
gpm version --json

# Check build details
gpm version --json | jq '.built'
```

### CI/CD Integration

```bash
# Check version in CI
gpm version --json > version-info.json

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

## Best Practices

### Version Management

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

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

### Compatibility

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

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

### Documentation

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

## Error Handling

### Common Issues

* **Version information unavailable**: Build information missing
* **JSON parsing error**: Invalid JSON output
* **Platform detection error**: Unsupported platform

### Troubleshooting

1. **Version information missing**: Rebuild CLI with proper build flags
2. **JSON parsing error**: Check CLI installation and integrity
3. **Platform detection error**: Verify platform compatibility

## Related Commands

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

## See Also

* [CLI Reference](/cli-reference/cli.md) - Complete command documentation
* [Installation](/getting-started/getting-started/installation.md) - Installation guide
* [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/utilities.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.