How to List Go Modern Guidelines Using the CLI for a Specific File

To list Go modern guidelines for a specific file using the CLI, run go-modern-guidelines list <path> which resolves the Go version from the file's module or workspace and filters the embedded guideline set to match.

The JetBrains/go-modern-guidelines repository provides a command-line interface implemented in internal/cli/cli.go that helps developers identify which modern Go practices apply to their codebase. When you need to list Go modern guidelines using the CLI for a specific file, the tool automatically inspects the nearest go.mod or go.work file to determine the appropriate Go version and returns relevant recommendations.

CLI Version Sources and Flags

The CLI supports three mutually exclusive methods for determining which Go version to use when generating guidelines. According to the source code in internal/cli/cli.go, the runList function validates that you only provide one of these sources (see lines 64–66).

Explicit Version Flag

Use --go-version <ver> to manually specify a Go version such as 1.24 or go1.24.3. This bypasses automatic file detection and forces the tool to use your specified version when filtering guidelines.

File-Based Resolution

The --file-path <path> flag points directly to a Go source file, go.mod, or go.work file. The CLI delegates version detection to goversion.Resolve in internal/goversion/goversion.go (lines 29–34), which inspects the file or locates the nearest module/work file to extract the go directive.

Positional Argument

Supply the file path as a bare positional argument (<path>). This functions identically to --file-path but uses a more concise syntax. This is the most common pattern when you want to list Go modern guidelines using the CLI for a specific file in your current working directory.

Practical Usage Examples

The following commands demonstrate how to invoke the list subcommand for different scenarios:

# List guidelines for the Go version declared in the nearest go.mod/go.work

go-modern-guidelines list ./path/to/my/file.go

# Explicitly override the version (useful when the file has no module)

go-modern-guidelines list --go-version 1.23 ./path/to/my/file.go

# Use the long flag form to specify a go.mod directly

go-modern-guidelines list --file-path ./path/to/go.mod

Each command produces a newline-separated list where each line follows the format <id>: <short description>.

Internal Resolution Pipeline

Understanding the internal flow helps troubleshoot unexpected behavior when listing guidelines.

Flag Validation and Dispatch

When you execute the list command, runList in internal/cli/cli.go first validates that exactly one version source has been provided (lines 64–66). It then calls goversion.Resolve on line 79 to obtain a normalized major.minor version string.

Version Resolution Logic

The goversion.Resolve function in internal/goversion/goversion.go handles the heavy lifting of version detection. If you provided a file path, it searches for a go directive in go.mod or go.work files (lines 29–34). If no version is found in the file hierarchy, it falls back to the locally installed Go toolchain.

Guideline Filtering and Output

Once the target version is determined, runList invokes guidelines.ListText from internal/guidelines/guidelines.go (lines 63–66). This function loads the embedded guidelines.json data and filters the guideline set to include only entries whose sinceVersion is less than or equal to the resolved Go version. The function then formats and returns the text output you see in the terminal.

Summary

• The go-modern-guidelines list command accepts a file path as either a positional argument (<path>) or via --file-path <path>.
• Version resolution occurs in internal/goversion/goversion.go via the Resolve function, which inspects go.mod/go.work files or falls back to the local toolchain.
• Explicit versioning is available through --go-version <ver> for files outside module boundaries.
• The output format displays each guideline as <id>: <short description>, filtered by the sinceVersion field in the embedded guidelines.json.
• Key implementation files include internal/cli/cli.go for command parsing and internal/guidelines/guidelines.go for data filtering.

Frequently Asked Questions

What happens if the file is not inside a Go module?

If you provide a path to a standalone .go file with no containing go.mod or go.work file, goversion.Resolve falls back to your locally installed Go toolchain version. Alternatively, you can force a specific version using the --go-version flag to ensure you get relevant guidelines.

Can I list guidelines for an entire directory instead of a single file?

While the CLI accepts directory paths, the version resolution logic in internal/goversion/goversion.go searches for go.mod or go.work files starting from that directory. The resulting guideline list applies to the Go version declared in those module files, effectively covering the entire module scope.

How does the tool handle pre-release or RC Go versions?

The Resolve function normalizes version strings to major.minor format. When using --go-version, you can supply extended version strings like go1.24rc1, but the system normalizes these to 1.24 before filtering guidelines in guidelines.ListText, ensuring you see all applicable recommendations for that minor version.

Where are the actual guideline definitions stored?

The guideline data is embedded into the binary from internal/guidelines/guidelines.json and loaded at runtime by functions in internal/guidelines/guidelines.go. This embedded JSON contains the sinceVersion fields that determine which guidelines appear in your CLI output based on the resolved Go version.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}