9.0 KiB
gopls CLI reference
The Go team documents this interface as experimental — "not efficient, complete, flexible, or officially supported." Treat it as a debugging and one-shot-scripting fallback, not the primary way to drive gopls; prefer the MCP tools or the native LSP tool when either is available (see mcp.md).
Table of contents
- Position syntax
- Global flags
- Shared write flags
- Navigation commands
- Diagnostics
- Transformation commands
- Code actions and code lenses
- Introspection
- CodeAction kind reference
Position syntax
Two interchangeable formats locate a point in a file:
file.go:line:column— both 1-indexed; columns count UTF-8 bytes, not runes or UTF-16 code units. Non-ASCII lines can disagree with what an editor reports if the editor counts differently.file.go:#1234— a 0-indexed byte offset from the start of the file.
gopls definition internal/cmd/definition.go:44:47
gopls definition internal/cmd/definition.go:#1270
Global flags
Flags accepted by gopls itself, before the subcommand:
| Flag | Value | Purpose |
|---|---|---|
-logfile=<path> |
a file path, or the literal string auto |
Log destination; auto picks a default output file instead of stderr |
-profile.cpu=<path> |
a file path | Write a CPU profile to this file |
-profile.mem=<path> |
a file path | Write a memory profile to this file |
-profile.alloc=<path> |
a file path | Write an allocation profile to this file |
-profile.block=<path> |
a file path | Write a blocking-profile to this file |
-profile.trace=<path> |
a file path | Write an execution trace to this file |
-v, -verbose |
boolean flag, no value | Verbose output |
-vv, -veryverbose |
boolean flag, no value | Very verbose output |
gopls mcp accepts its own, narrower flag set: -listen=<addr> (run over SSE/HTTP instead of stdio), -logfile=<path> (defaults to stderr), and -rpc.trace (cannot be combined with -listen).
Shared write flags
Every command that can modify source (format, imports, rename, codeaction, codelens, execute) accepts this same set — each is a boolean flag, no value:
| Flag | Purpose |
|---|---|
-w, -write |
Write the edited content back to the source file(s) |
-d, -diff |
Print a unified diff instead of writing |
-l, -list |
Print only the names of the files that would be/were edited |
-preserve |
Combined with -w: keep a copy of each original file before overwriting |
None of these are mutually exclusive with each other; passing none of them just computes the edit without printing or writing it.
Navigation commands
| Command | Flags | Example | Notes |
|---|---|---|---|
definition |
-json (boolean), -markdown (boolean) |
gopls definition helper/helper.go:8:6 |
-json for structured output, -markdown to render doc comments as Markdown |
references |
-d, -declaration (boolean) |
gopls references helper/helper.go:8:6 |
Includes the declaration itself in the results when set |
implementation |
none | gopls implementation helper/helper.go:8:6 |
— |
call_hierarchy |
none | gopls call_hierarchy helper/helper.go:8:6 |
Static calls only |
symbols |
none | gopls symbols helper/helper.go |
File-scoped outline |
workspace_symbol |
-matcher=<value> — one of fuzzy, fastfuzzy, casesensitive, caseinsensitive (default caseinsensitive) |
gopls workspace_symbol -matcher fuzzy 'wsymbols' |
Matching algorithm for the query |
signature |
none | gopls signature helper/helper.go:8:6 |
Function signature at position |
highlight |
none | gopls highlight helper/helper.go:8:6 |
Same-symbol identifier highlights |
folding_ranges |
none | gopls folding_ranges helper/helper.go |
Collapsible regions |
links |
-json (boolean) |
gopls links internal/cmd/check.go |
Structured output when set |
prepare_rename |
none | gopls prepare_rename helper/helper.go:8:6 |
Validates a rename is possible at this position before attempting it |
semtok |
none | gopls semtok internal/cmd/semtok.go |
Semantic token dump |
Diagnostics
| Command | Flags | Example |
|---|---|---|
check |
-severity=<value> — one of hint, info, warning, error (default warning); reports diagnostics at or above this severity |
gopls check -severity=error internal/cmd/check.go |
Transformation commands
All of these additionally accept the shared write flags above.
| Command | Positional args | Example | Notes |
|---|---|---|---|
format |
one or more <filerange> (a file, or a range within one) |
gopls format -w internal/cmd/check.go |
Canonical gofmt-equivalent; ignores client formatting options |
imports |
<filename> |
gopls imports -w internal/cmd/check.go |
Adds/removes/sorts imports |
rename |
<position> <new-name> |
gopls rename helper/helper.go:8:6 Foo |
<new-name> is a plain identifier — validate first with prepare_rename if unsure |
Code actions and code lenses
codeaction and codelens additionally accept the shared write flags.
| Command | Extra flags | Notes |
|---|---|---|
codeaction |
-kind=<value> — comma-separated list of kinds, see CodeAction kind reference below; -title=<regex> — filter actions by title; -exec (boolean) — execute the first match instead of only listing |
-kind=refactor matches every kind nested under it (kinds are hierarchical); only one action executes per invocation — there is no conflict resolution for applying more than one; actions of kind source.test are excluded unless explicitly requested via -kind |
codelens |
-exec (boolean) — run the first matching lens instead of only listing |
Takes <file>, <file:line>, or <file> <title> as positional args |
execute |
none beyond the shared write flags | Takes <command> <json-argument> — sends a raw LSP ExecuteCommand request; gopls's command set (command.Interface) is unstable and may change between versions |
# List available code actions for a range
gopls codeaction -kind=quickfix ./gopls/main.go
# Execute the first matching action and show a diff
gopls codeaction -kind=quickfix -exec -diff ./gopls/main.go
# Filter by title (regex) in addition to kind
gopls codeaction -kind=refactor.rewrite -title 'Fill struct' -exec -w file.go:12:3
# Code lenses: list, or run a specific one
gopls codelens a_test.go # list lenses in a file
gopls codelens a_test.go:10 # list lenses on line 10
gopls codelens a_test.go "run test" # list gopls.run_tests commands
gopls codelens -exec a_test.go:10 "run test" # run a specific test
# Execute a raw LSP ExecuteCommand
gopls execute gopls.add_import '{"ImportPath": "fmt", "URI": "file:///hello.go"}'
gopls execute gopls.run_tests '{"URI": "file:///a_test.go", "Tests": ["Test"]}'
gopls execute gopls.list_known_packages '{"URI": "file:///hello.go"}'
Introspection
| Command | Flags | Notes |
|---|---|---|
stats |
-anon (boolean) |
JSON summary of workspace info relevant to performance; populates the file cache as a side effect. -anon redacts fields that could leak user/file names or source text |
version |
none | Print gopls version info |
api-json |
none | Print gopls' full API surface as JSON |
bug |
none | Report a bug in gopls |
licenses |
none | Print licenses of bundled software |
gopls stats
gopls stats -anon
gopls version
gopls api-json
gopls bug
gopls licenses
CodeAction kind reference
Passed to -kind on codeaction (comma-separated, hierarchical — refactor matches all refactor.*):
gopls.doc.features
quickfix
refactor
refactor.extract
refactor.extract.constant
refactor.extract.function
refactor.extract.method
refactor.extract.toNewFile
refactor.extract.variable
refactor.inline
refactor.inline.call
refactor.rewrite
refactor.rewrite.changeQuote
refactor.rewrite.fillStruct
refactor.rewrite.fillSwitch
refactor.rewrite.invertIf
refactor.rewrite.joinLines
refactor.rewrite.removeUnusedParam
refactor.rewrite.splitLines
source
source.assembly
source.doc
source.fixAll
source.freesymbols
source.organizeImports
source.test
A few additional kinds exist beyond this -kind-documented set but are reachable only through editor UI or execute/code lens, not by name filter: refactor.extract.variable-all, refactor.extract.constant-all, refactor.inline.variable, refactor.rewrite.moveParamLeft, refactor.rewrite.moveParamRight, refactor.rewrite.eliminateDotImport, refactor.rewrite.addTags, refactor.rewrite.removeTags, refactor.rewrite.implementInterface, source.addTest, source.splitPackage, source.toggleCompilerOptDetails. See features.md for what each one does.