# How to List Go Modern Guidelines Using the CLI for a Specific File > Easily list Go modern guidelines for a specific file using the CLI. Run go-modern-guidelines list to filter rules based on your file's Go version and module. - Repository: [JetBrains/go-modern-guidelines](https://github.com/jetbrains/go-modern-guidelines) - Tags: how-to-guide - Published: 2026-08-30 --- **To list Go modern guidelines for a specific file using the CLI, run `go-modern-guidelines list ` 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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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 ` 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 ` 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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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 (``). 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: ```bash # 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 `: `. ## 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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go) (lines 63–66). This function loads the embedded [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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 (``) or via `--file-path `. - **Version resolution** occurs in [`internal/goversion/goversion.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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 ` for files outside module boundaries. - The **output format** displays each guideline as `: `, filtered by the `sinceVersion` field in the embedded [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json). - Key implementation files include [`internal/cli/cli.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go) for command parsing and [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.json) and loaded at runtime by functions in [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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.