Go Package Discovery (pkgsite-cli)
Specialist for querying pkg.go.dev metadata through
pkgsite-cli,
the reference CLI for the pkg.go.dev v1beta API. For
programmatic integrations, use the REST API directly; see references/api.md.
Introduced in the pkg.go.dev API blog post.
When to Use
- Discovering or comparing third-party Go packages not present locally
- Inspecting module versions, vulnerabilities, licenses, or README content
- Listing exported symbols, imports, or reverse dependencies for a package
- Scripting pkg.go.dev lookups with
-json output
When Not to Use
- Reading documentation for packages in the local module cache (use
go doc)
- Serving docs for local or private packages (use
cmd/pkgsite web server)
- Resolving ambiguous import paths without specifying the module
Core Workflow
- Install --
go install golang.org/x/pkgsite/cmd/internal/pkgsite-cli@latest
- Choose interface -- CLI for terminal/scripts; REST API for application code
- Pick command --
search for discovery; package or module for inspection
- Set flags -- Request only needed data; use
-json for machine output
- Handle ambiguity -- Pass
-module when the API reports multiple candidates
Reference Guide
| Topic |
Reference |
Load When |
| Package inspection |
references/package.md |
Metadata, docs, symbols, imports, imported-by, licenses |
| Module inspection |
references/module.md |
Versions, packages, vulnerabilities, README |
| Search |
references/search.md |
Finding packages or symbols on pkg.go.dev |
| REST API |
references/api.md |
Direct HTTP access, OpenAPI spec, curl, pagination |
Commands
| Command |
Purpose |
pkgsite-cli search <query> |
Search for packages (or symbols with -symbol) |
pkgsite-cli package <path>[@version] |
Inspect a package |
pkgsite-cli module <module>[@version] |
Inspect a module |
pkgsite-cli help |
Print usage for all commands |
pkgsite-cli version |
Print CLI version and Go toolchain |
Shared flags on package, module, and search: -json, -limit (default 25),
-server (default https://pkg.go.dev), -timeout (default 30s), -x (print URLs).
Run pkgsite-cli <command> -h for command-specific flags.
Version Syntax
Append @version to paths for semver tags (v1.2.3) or master/main branches.
Omit @version for the latest tagged release.
Constraints
MUST DO
- Place flags before positional arguments
- Use
-module when the API returns ambiguous path candidates
- Use
-json in scripts; check exit code for failures
- Prefer
pkgsite-cli or the REST API over scraping pkg.go.dev HTML
MUST NOT DO
- Assume the CLI interface is stable (marked experimental upstream)
- Rely on the web UI's "longest module path" resolution
- Put flags after positional arguments
- Use
pkgsite-cli instead of go doc on local code
Quick Examples
pkgsite-cli search -limit 5 "structured logging"
pkgsite-cli package -symbols -imported-by github.com/google/go-cmp/cmp
pkgsite-cli module -versions -packages github.com/google/go-cmp
pkgsite-cli search -json -limit 10 uuid | jq '.items[].packagePath'
Tool Comparison
| Tool |
Scope |
go doc |
Local module cache |
cmd/pkgsite |
Local web server for downloaded packages |
pkgsite-cli |
Remote metadata: search, versions, vulns, imported-by, licenses |
| REST API |
Same data as CLI; best for application integrations |
Source: lrstanley/skills — distributed by TomeVault.
1---2name: lrstanley-skills-golang-packages3description: Go Package Discovery (pkgsite-cli)4---56# Go Package Discovery (pkgsite-cli)78Specialist for querying [pkg.go.dev](https://pkg.go.dev/) metadata through9[pkgsite-cli](https://github.com/golang/pkgsite/tree/master/cmd/internal/pkgsite-cli),10the reference CLI for the [pkg.go.dev v1beta API](https://pkg.go.dev/api). For11programmatic integrations, use the REST API directly; see `references/api.md`.1213Introduced in the [pkg.go.dev API blog post](https://go.dev/blog/pkgsite-api).1415## When to Use1617- Discovering or comparing third-party Go packages not present locally18- Inspecting module versions, vulnerabilities, licenses, or README content19- Listing exported symbols, imports, or reverse dependencies for a package20- Scripting pkg.go.dev lookups with `-json` output2122## When Not to Use2324- Reading documentation for packages in the local module cache (use `go doc`)25- Serving docs for local or private packages (use `cmd/pkgsite` web server)26- Resolving ambiguous import paths without specifying the module2728## Core Workflow29301. **Install** -- `go install golang.org/x/pkgsite/cmd/internal/pkgsite-cli@latest`312. **Choose interface** -- CLI for terminal/scripts; REST API for application code323. **Pick command** -- `search` for discovery; `package` or `module` for inspection334. **Set flags** -- Request only needed data; use `-json` for machine output345. **Handle ambiguity** -- Pass `-module` when the API reports multiple candidates3536## Reference Guide3738| Topic | Reference | Load When |39| --- | --- | --- |40| Package inspection | `references/package.md` | Metadata, docs, symbols, imports, imported-by, licenses |41| Module inspection | `references/module.md` | Versions, packages, vulnerabilities, README |42| Search | `references/search.md` | Finding packages or symbols on pkg.go.dev |43| REST API | `references/api.md` | Direct HTTP access, OpenAPI spec, curl, pagination |4445## Commands4647| Command | Purpose |48| --- | --- |49| `pkgsite-cli search <query>` | Search for packages (or symbols with `-symbol`) |50| `pkgsite-cli package <path>[@version]` | Inspect a package |51| `pkgsite-cli module <module>[@version]` | Inspect a module |52| `pkgsite-cli help` | Print usage for all commands |53| `pkgsite-cli version` | Print CLI version and Go toolchain |5455Shared flags on `package`, `module`, and `search`: `-json`, `-limit` (default 25),56`-server` (default `https://pkg.go.dev`), `-timeout` (default 30s), `-x` (print URLs).57Run `pkgsite-cli <command> -h` for command-specific flags.5859## Version Syntax6061Append `@version` to paths for semver tags (`v1.2.3`) or `master`/`main` branches.62Omit `@version` for the latest tagged release.6364## Constraints6566### MUST DO6768- Place flags **before** positional arguments69- Use `-module` when the API returns ambiguous path candidates70- Use `-json` in scripts; check exit code for failures71- Prefer `pkgsite-cli` or the REST API over scraping pkg.go.dev HTML7273### MUST NOT DO7475- Assume the CLI interface is stable (marked experimental upstream)76- Rely on the web UI's "longest module path" resolution77- Put flags after positional arguments78- Use `pkgsite-cli` instead of `go doc` on local code7980## Quick Examples8182```bash83pkgsite-cli search -limit 5 "structured logging"84pkgsite-cli package -symbols -imported-by github.com/google/go-cmp/cmp85pkgsite-cli module -versions -packages github.com/google/go-cmp86pkgsite-cli search -json -limit 10 uuid | jq '.items[].packagePath'87```8889## Tool Comparison9091| Tool | Scope |92| --- | --- |93| `go doc` | Local module cache |94| `cmd/pkgsite` | Local web server for downloaded packages |95| `pkgsite-cli` | Remote metadata: search, versions, vulns, imported-by, licenses |96| REST API | Same data as CLI; best for application integrations |9798---99> Source: [lrstanley/skills](https://github.com/lrstanley/skills) — distributed by [TomeVault](https://tomevault.io).100<!-- tomevault:4.0:skill_md:2026-06-15 -->
tomevault-io