pkgsite-cli

A command-line interface for querying pkg.go.dev.

Currently the API is on v1beta, but we expect to move to v1 soon.

Related to https://go.dev/issue/76718.

Quick start

To install the pkgsite-cli tool, run:

go install golang.org/x/pkgsite/cmd/internal/pkgsite-cli@latest

Motivation

The pkg.go.dev service exposes a REST API for package and module metadata. (TODO: link to the API doc). pkgsite-cli provides a lightweight CLI that queries the API and prints results for both humans and automated tools. There is no official SDK for the API, but this tool serves as a reference client implementation that developers can use in other projects.

Relationship to existing tools

  • go doc renders documentation for packages available locally. pkgsite-cli does not replace it for reading local documentation.
  • cmd/pkgsite is a webserver that serves documentation for packages available locally. It does not provide full version listings, vulnerability reports, reverse dependencies, licenses, or search capabilities (yet).
  • pkgsite-cli provides access to information go doc or a local instance of cmd/pkgsite cannot reach: version listings, vulnerability reports, reverse dependencies, licenses, documentation of modules/packages, and search results for packages not yet downloaded.

Rule of thumb: Use go doc for local code; use pkgsite-cli for package discovery and metadata lookup.

Commands

Run pkgsite-cli <command> -h for details on available flags for each command.

Available commands:

  • package
  • module
  • search

More commands will be added.

Package info

pkgsite-cli package [flags] <package>[@version]

Example:

$ pkgsite-cli package encoding/json
encoding/json (standard library)
  Module:   std
  Version:  go1.24.2 (latest)

Module info

pkgsite-cli module [flags] <module>[@version]

Search

pkgsite-cli search [flags] <query>

Details

  • Ambiguous path: CLI shows candidates. Use --module to resolve.
  • Pagination: JSON returns nextPageToken. Use --token to continue.

Status and Implementation

  • Experimental: This tool is currently a prototype.
  • Minimal Dependencies: To facilitate potential migration to other repositories (e.g. x/tools), the tool depends only on the Go standard library.
  • Duplicated Types: API request/response types are duplicated in the tool's source instead of imported from pkgsite for now. We ruled out releasing a full SDK because the REST API is simple enough to consume directly. This keeps the tool self-contained. If this tool remains in this repo, however, we can eliminate this duplication and use the internal package.