# How Guidelines Data Is Embedded in the go-modern-guidelines CLI

> Discover how go-modern-guidelines embeds its data as a compiled-in JSON asset. Learn how the CLI parses guideline definitions at startup for list and explain commands.

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

---

**The go-modern-guidelines CLI embeds its guideline definitions as a compiled-in JSON asset using Go's `embed` package, parsing the data at startup into a slice of structs that the `list` and `explain` commands consume.**

The JetBrains/go-modern-guidelines project distributes Go best practices as a standalone command-line tool. To ensure seamless operation without external dependencies, the **guidelines data embedded into the go-modern-guidelines CLI** is baked directly into the binary at compile time. This approach guarantees that every distribution contains the complete, version-matched rule set regardless of the execution environment.

## How the Embedding Works

### Embedding the JSON Asset

In [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go), the source file [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json) is embedded using the `//go:embed` directive. This directive instructs the Go compiler to store the specified file's contents as a byte slice within the binary.

```go
//go:embed guidelines.json
var modernGoGuidelinesJSON []byte

```

This declaration places the entire JSON content into the `modernGoGuidelinesJSON` variable, making it available at runtime without filesystem access.

### Parsing the Guideline Data

At program initialization, the `mustLoadModernGoGuidelines()` function parses the embedded byte slice. According to the JetBrains/go-modern-guidelines source code, this function uses a schema-generated parser to validate and convert the JSON into strongly-typed Go structs.

The resulting slice of `modernGoGuideline` structs is stored in the package-level variable `modernGoGuidelines`, providing in-memory access to all guideline definitions throughout the application lifecycle.

## Accessing Embedded Data from CLI Commands

The CLI implementation in [`internal/cli/cli.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go) delegates all data retrieval to the `guidelines` package, ensuring both commands operate on the same embedded dataset.

### The list Command

When users run the `list` subcommand, the CLI invokes `guidelines.ListText(targetVersion)` (referenced at lines 84-86 in [`internal/cli/cli.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go)). This function filters the embedded guidelines based on the target Go version and returns a concise summary of applicable rule IDs and descriptions.

### The explain Command

For detailed inspections, the `explain` command calls `guidelines.ExplainText(guidelineIDs)` (found at lines 6-12 in [`internal/cli/cli.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go)) to fetch full documentation, including code examples and rationales. This retrieval occurs against the in-memory `modernGoGuidelines` slice populated during startup.

## Benefits of Compile-Time Embedding

Embedding the **guidelines data embedded into the go-modern-guidelines CLI** directly into the binary provides significant operational advantages. The tool requires no external data files, configuration directories, or network access to function. This design ensures the guideline set remains available even when the binary is distributed independently or executed in isolated, air-gapped environments.

## Summary

- The `//go:embed` directive in [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go) imports [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json) into the `modernGoGuidelinesJSON` byte slice.
- `mustLoadModernGoGuidelines()` parses the embedded JSON into a slice of `modernGoGuideline` structs at startup.
- The `list` command consumes this data via `guidelines.ListText(targetVersion)` to filter by Go version.
- The `explain` command retrieves details via `guidelines.ExplainText(guidelineIDs)` from the in-memory cache.
- Compile-time embedding enables single-binary distribution with zero external file dependencies.

## Frequently Asked Questions

### What file format stores the guidelines definitions?

The guidelines are stored as a JSON file located at [`internal/guidelines/guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.json). This file contains structured definitions including guideline IDs, summaries, detailed explanations, and code examples.

### How does the CLI access the embedded guidelines?

The CLI accesses the data through the `guidelines` package API. The `list` command calls `guidelines.ListText(targetVersion)` while the `explain` command calls `guidelines.ExplainText(guidelineIDs)`, both operating on the `modernGoGuidelines` slice populated during package initialization.

### Why embed the data instead of loading it from disk?

Embedding the JSON directly into the binary using the `//go:embed` directive ensures the CLI operates as a single standalone file. This guarantees that guideline definitions remain available even when the binary is moved, renamed, or distributed without accompanying data files.

### Where in the source code does the embedding logic reside?

The embedding occurs in [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go) at lines 29-30, where the `//go:embed guidelines.json` directive precedes the `modernGoGuidelinesJSON` variable declaration. This file also contains the `mustLoadModernGoGuidelines()` function that handles parsing.