# Why the go-modern-guidelines CLI Installs to ~/.cache/go-modern-guidelines and How Caching Works

> Discover why go-modern-guidelines CLI installs to ~/.cache/go-modern-guidelines and how its caching mechanism speeds up your workflow by avoiding recompilation.

- Repository: [JetBrains/go-modern-guidelines](https://github.com/jetbrains/go-modern-guidelines)
- Tags: internals
- Published: 2026-09-04

---

**The go-modern-guidelines CLI installs into `~/.cache/go-modern-guidelines` to isolate the binary from your `$GOPATH/bin`, comply with XDG Base Directory standards, and enable safe removal, while the cached executable is reused on subsequent runs without recompilation.**

The JetBrains/go-modern-guidelines repository delivers a command-line tool for enforcing Go best practices. Unlike standard Go binaries that populate `$GOPATH/bin` or `$HOME/go/bin`, this project deliberately redirects its installation target to the user's XDG cache directory via the `GOBIN` environment variable. This architectural decision ensures version isolation, simplifies cleanup, and aligns with JetBrains plugin conventions for transient, user-specific tooling.

## Why the CLI Installs to ~/.cache/go-modern-guidelines

### Isolation from Default Go Binary Paths

Placing the binary in `~/.cache/go-modern-guidelines` keeps it separate from your global `$GOPATH/bin` directory. This prevents version clashes with other Go tools you may have installed and avoids polluting your default Go binary path. The **dev-install** script in [`scripts/dev-install.sh`](https://github.com/JetBrains/go-modern-guidelines/blob/main/scripts/dev-install.sh) explicitly overrides the installation target:

```bash

# In scripts/dev-install.sh

export GOBIN="${HOME}/.cache/go-modern-guidelines"
go install ./...                # builds the binary into $GOBIN

```

### Compliance with XDG Base Directory Standards

The `$HOME/.cache` directory follows the XDG Base Directory Specification, which designates it as the recommended location for transient, rebuildable artifacts. This location is per-user, writable without elevated privileges, and consistently available across Linux, macOS, and Windows (via WSL). By adhering to this standard, the go-modern-guidelines CLI respects platform conventions for cached data.

### Simplified Cleanup and Version Management

Because the folder is explicitly designated for cached data, deleting `~/.cache/go-modern-guidelines` completely removes the tool without affecting your Go source code, module cache, or other environment settings. This makes version switching trivial—simply delete the directory and rerun the installation script to obtain a fresh binary.

### Alignment with JetBrains Tooling Conventions

The repository functions as a JetBrains "skill" or plugin component. JetBrains tooling expects cached executables under `~/.cache` for fast reuse across IDE sessions. Installing the go-modern-guidelines binary to this location ensures seamless integration with JetBrains IDEs that invoke the CLI for real-time code analysis.

## How the go-modern-guidelines Caching Mechanism Works

### First Installation and Compilation

During initial setup, the **dev-install** script creates the `~/.cache/go-modern-guidelines` directory if it does not exist, then executes `go install`. Go compiles the source code, writes the resulting `go-modern-guidelines` executable into the cache directory, and stores any module dependencies in the standard Go module cache (`$GOPATH/pkg/mod` or `$GOMODCACHE`).

### Reusing Cached Executables

When you invoke the CLI after installation, the binary is already present in the cache directory, so no recompilation occurs. The installation script checks the existence (and optionally the modification timestamp) of the cached binary before deciding whether to trigger a rebuild. This design ensures sub-second startup times for repeated invocations.

### Embedded Guidelines Data

The guidelines themselves are embedded at compile time using the `//go:embed` directive in [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go). The source file embeds [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json) directly into the binary:

```go
// In internal/guidelines/guidelines.go
//go:embed guidelines.json
var guidelinesData []byte

```

Because the data is compiled into the executable, the CLI requires no additional runtime downloads or separate cache management for guideline updates. The cached binary contains the complete, up-to-date rule set.

### Updating the Cached Binary

To upgrade to a newer version, rerun the installation script or execute `go install` with a specific version tag. The script overwrites the existing executable in `~/.cache/go-modern-guidelines`, treating the cache directory as the single source of truth for the CLI binary.

## Installing and Updating the CLI

Install the tool using the provided script, which automatically handles the cache directory setup:

```bash

# Run the cache-aware install helper

bash scripts/dev-install.sh

```

Invoke the CLI directly or ensure the cache directory is in your `$PATH`:

```bash

# Direct invocation

~/.cache/go-modern-guidelines/go-modern-guidelines list

# Or if PATH includes the cache directory

go-modern-guidelines list

```

Update to the latest version by rerunning the install script:

```bash

# Overwrites the cached binary with the new version

bash scripts/dev-install.sh

```

## Key Implementation Files

- **[`scripts/dev-install.sh`](https://github.com/JetBrains/go-modern-guidelines/blob/main/scripts/dev-install.sh)**: Sets `GOBIN="${HOME}/.cache/go-modern-guidelines"` and executes `go install ./...` to compile the binary into the XDG cache location.
- **[`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go)**: Implements `//go:embed guidelines.json` to bundle guideline data directly into the compiled executable, eliminating runtime network requests.
- **[`internal/cli/cli.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go)**: Implements the command-line interface logic executed by the cached binary.
- **Cached binary location**: `~/.cache/go-modern-guidelines/go-modern-guidelines` serves as the persistent executable reused across sessions.

## Summary

- The go-modern-guidelines CLI installs to `~/.cache/go-modern-guidelines` via the `GOBIN` variable in [`scripts/dev-install.sh`](https://github.com/JetBrains/go-modern-guidelines/blob/main/scripts/dev-install.sh) to isolate it from `$GOPATH/bin`.
- This location follows XDG Base Directory standards, requires no elevated permissions, and allows safe deletion without side effects.
- The binary embeds [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json) at compile time using `//go:embed`, so no runtime downloads are necessary.
- Subsequent invocations reuse the cached executable, while updates overwrite the binary in the same directory.
- The design integrates specifically with JetBrains tooling expectations for cached, user-specific executables.

## Frequently Asked Questions

### Why doesn't go-modern-guidelines use $GOPATH/bin like other Go tools?

The project prioritizes isolation and clean uninstallation. By using `~/.cache/go-modern-guidelines` instead of `$GOPATH/bin`, the tool avoids conflicts with other installed versions and allows users to delete the entire directory without affecting their broader Go environment. This approach also aligns with JetBrains plugin architecture, which expects cached executables in the XDG cache location.

### How do I update the cached binary when a new version is released?

Simply rerun the installation script (`bash scripts/dev-install.sh`) or execute `go install github.com/JetBrains/go-modern-guidelines@latest` with `GOBIN` set to `"${HOME}/.cache/go-modern-guidelines"`. The new compilation overwrites the existing cached executable, preserving the same installation path while updating the underlying code and embedded guidelines.

### Does the CLI download guidelines data at runtime or include it in the binary?

The CLI includes the guidelines data directly within the binary at compile time. The file [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go) uses the `//go:embed guidelines.json` directive to bundle the JSON data, meaning the cached executable is self-contained. No network requests or additional cache directories are required to access the rule definitions during execution.

### Is it safe to delete the ~/.cache/go-modern-guidelines directory?

Yes. Deleting this directory removes only the compiled CLI binary and any related build artifacts stored there. Because the directory is strictly a cache location according to XDG standards, removal does not affect your Go module cache, source code, IDE configuration, or other system tools. You can safely delete it and reinstall the tool later using the standard installation script.