apstndb/apstndb-pkgsite

pkgsite API Skill

pkg.go.dev exposes a JSON API for public Go module and package metadata. Use it for discovery and ecosystem context. Use local go doc lookups for local precision: current workspace code, replace directives, unpublished/private modules, unexported symbols, source (-src), or exact local toolchain behavior.

Tool Choice

Use pkgsite-cli for quick interactive queries when available. Check with command -v pkgsite-cli; in mise-managed environments, mise which pkgsite-cli or mise x -- pkgsite-cli ... may work. Raw API examples are always a suitable fallback.

Prefer raw curl + jq for scripts, reusable instructions, pagination loops, or when exact JSON fields matter. If jq is unavailable, use another JSON parser or inspect the raw JSON. The API contract is the stable surface; pkgsite-cli is a convenience wrapper.

Use raw API calls for operations that pkgsite-cli v0.1.0 does not expose:

• Server-side filter on list routes (search, versions, packages, symbols, imported-by, vulns).
• Package-path vulnerability lookup through /v1beta/vulns/{path}; pkgsite-cli module -vulns expects a module path.
• Fetching or validating the API contract/OpenAPI document itself.

Avoid scraping pkg.go.dev HTML unless the API does not expose the view you need.

Common Tasks

Search package candidates:

pkgsite-cli search -limit 10 errgroup

curl -sL 'https://pkg.go.dev/v1beta/search?q=errgroup&limit=10' \
  | jq '.items[] | {packagePath, modulePath, version, synopsis}'

Inspect package metadata, rendered docs, examples, imports, or exact symbols after selecting a package:

pkgsite-cli package golang.org/x/sync/errgroup
pkgsite-cli package -symbols golang.org/x/sync/errgroup
pkgsite-cli package -doc md -examples golang.org/x/sync/errgroup
pkgsite-cli package -imports -json golang.org/x/sync/errgroup | jq .

curl -sL 'https://pkg.go.dev/v1beta/package/golang.org/x/sync/errgroup?doc=md&examples=true' \
  | jq -r '.docs'
curl -sL 'https://pkg.go.dev/v1beta/symbols/golang.org/x/sync/errgroup?limit=200' \
  | jq '.symbols.items[] | {name, kind, synopsis, parent}'

Inspect module versions, packages, README, licenses, or vulnerabilities:

pkgsite-cli module -versions golang.org/x/sync
pkgsite-cli module -packages golang.org/x/sync
pkgsite-cli module -readme -licenses -json golang.org/x/sync | jq .
pkgsite-cli module -vulns golang.org/x/image

curl -sL 'https://pkg.go.dev/v1beta/versions/golang.org/x/sync?limit=20' | jq '.items[].version'
curl -sL 'https://pkg.go.dev/v1beta/packages/golang.org/x/sync?limit=200' \
  | jq '.packages.items[] | {path, synopsis}'
curl -sL 'https://pkg.go.dev/v1beta/vulns/golang.org/x/image' | jq .

Check public importers:

pkgsite-cli package -imported-by -limit 20 golang.org/x/sync/errgroup
curl -sL 'https://pkg.go.dev/v1beta/imported-by/golang.org/x/sync/errgroup?limit=20' \
  | jq '.importedBy.items[]'

Use API-only filtering when the result set is large:

curl -G -sL 'https://pkg.go.dev/v1beta/symbols/golang.org/x/time/rate' \
  --data-urlencode 'filter=kind=="Method" && parent=="Limiter"' \
  | jq '.symbols.items[] | {name, synopsis}'

Use the raw vulnerability endpoint when the input is a package path, not just a module:

curl -sL 'https://pkg.go.dev/v1beta/vulns/golang.org/x/image/draw' | jq .

For version-specific package data, use @version with pkgsite-cli or version= with the API:

pkgsite-cli package -symbols google.golang.org/[email protected]
curl -sL 'https://pkg.go.dev/v1beta/package/google.golang.org/grpc?version=v1.60.0' | jq .

Coordination With go doc

Use pkgsite first when the package/module is unknown, when you need public versions or importers, or when you need rendered examples without downloading source. Then switch to local go doc for detailed symbol docs. This is not a go doc usage skill, so keep local lookup examples minimal.

pkgsite-cli search -limit 5 'rate limiter'
pkgsite-cli package -symbols golang.org/x/time/rate

# In a local module context where the package is available:
go doc golang.org/x/time/rate.Limiter
go doc golang.org/x/time/rate.Limiter.Wait

Do not replace local docs with pkgsite for local code review. pkgsite only sees public data indexed by pkg.go.dev and may not reflect local changes or private dependencies.

API Reference Notes

Base URL: https://pkg.go.dev/v1beta

Official docs:

• API documentation: https://pkg.go.dev/v1beta/api
• OpenAPI specification: https://pkg.go.dev/v1beta/openapi.yaml
• pkgsite-cli command documentation: https://pkg.go.dev/golang.org/x/pkgsite/cmd/internal/pkgsite-cli

Core routes:

• /package/{path}: package metadata; optional module, version, goos, goarch, doc, examples, imports, licenses
• /module/{path}: module metadata; optional version, readme, licenses
• /versions/{module}: module versions
• /packages/{module}: packages in a module
• /search?q={query}: package search; optional symbol
• /symbols/{package}: exported symbols for a package
• /imported-by/{package}: public reverse importers outside the same module
• /vulns/{path}: public Go vulnerability database data

Caveats:

• If version is omitted, the API uses latest. It accepts semantic versions, latest, main, and master.
• Package paths can be ambiguous across modules. If an error response includes candidates, retry with module=<module path> or pkgsite-cli package -module <module> ....
• pkg.go.dev may not list or render newly tagged, uncached, or not-yet-indexed versions. Do not treat absence from pkgsite as proof a version does not exist; verify with go list -m -versions, go mod download, repository tags, or the module proxy when exact availability matters.
• List responses may include nextPageToken; repeat the same request with token=<token> or the relevant pkgsite-cli token flag.
• filter is a Go boolean expression over response fields, not a bare regular expression. Percent-encode query parameters.
• search?symbol= searches packages with symbol constraints but is not a precise symbol lookup for a known package. Prefer /symbols/{package} or pkgsite-cli package -symbols once the package path is known.
• A successful vulnerability lookup may still return no vulnerability entries, for example { "items": null, "total": 0 } from the raw API or only module metadata from pkgsite-cli module -vulns.
• Package documentation returned by doc=md, doc=text, or doc=html is in the JSON field .docs.