golang-pkg-go-dev

# godig sample output

Representative `-o md` output for each command, captured against `godig` v0.2.0. Empty cells are shown as `—`. Field sets mirror the underlying APIs — pkg.go.dev for most commands, the Go vulnerability database (`vuln.go.dev`, OSV) for `vulns` — and may grow over time.

## Table of Contents

- [overview](#overview)
- [search](#search)
- [package info](#package-info)
- [package imports](#package-imports)
- [versions](#versions)
- [major-versions](#major-versions)
- [imported-by](#imported-by)
- [vulns](#vulns)
- [dependencies](#dependencies)
- [module info](#module-info)
- [packages](#packages)
- [symbols](#symbols)
- [symbol doc](#symbol-doc)
- [Raw / large output](#raw--large-output)

## overview

`godig overview github.com/samber/ro -o md`

| field             | value                          |
| ----------------- | ------------------------------ |
| isStandardLibrary | false                          |
| latestVersion     | v0.3.0                         |
| licenses          | ["Apache-2.0"]                 |
| modulePath        | github.com/samber/ro           |
| name              | ro                             |
| path              | github.com/samber/ro           |
| recentVersions    | ["v0.3.0","v0.2.0","v0.1.0"]   |
| repoUrl           | <https://github.com/samber/ro> |

## search

`godig search ro --limit 3 -o md`

| modulePath | packagePath | synopsis | version |
| --- | --- | --- | --- |
| github.com/samber/ro | github.com/samber/ro | — | v0.3.0 |
| github.com/blevesearch/bleve | github.com/blevesearch/bleve/analysis/lang/ro | — | v1.0.14 |
| github.com/blevesearch/bleve/v2 | github.com/blevesearch/bleve/v2/analysis/lang/ro | — | v2.6.0 |

## package info

`godig package info github.com/samber/ro -o md`

| field             | value                |
| ----------------- | -------------------- |
| goarch            | all                  |
| goos              | all                  |
| isLatest          | true                 |
| isRedistributable | true                 |
| isStandardLibrary | false                |
| modulePath        | github.com/samber/ro |
| name              | ro                   |
| path              | github.com/samber/ro |
| version           | v0.3.0               |

## package imports

`godig package imports github.com/samber/ro -o md` — a plain list (no `--limit`):

```text
- context
- errors
- fmt
- ...
```

## versions

`godig versions github.com/samber/ro --limit 3 -o md`

| commitTime | deprecated | deprecationReason | hasGoMod | isRedistributable | latestVersion | modulePath | retracted | retractionReason | version |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 2026-03-02T15:16:08Z | false | — | true | true | v0.3.0 | github.com/samber/ro | false | — | v0.3.0 |
| 2025-10-25T22:20:38Z | false | — | true | false | v0.3.0 | github.com/samber/ro | false | — | v0.2.0 |
| 2025-10-14T12:21:03Z | false | — | true | false | v0.3.0 | github.com/samber/ro | false | — | v0.1.0 |

## major-versions

`godig major-versions github.com/samber/lo -o md`

| isLatest | major | modulePath           | version |
| -------- | ----- | -------------------- | ------- |
| true     | v1    | github.com/samber/lo | v1.53.0 |

## imported-by

`godig imported-by github.com/samber/ro --limit 3 -o md`

| package                                |
| -------------------------------------- |
| github.com/CooperCorona/websocket      |
| github.com/CooperCorona/websocket/test |
| github.com/samber/ro/ee/plugins/otel   |

## vulns

`godig vulns github.com/dgrijalva/jwt-go -o md`

Since v0.2.0 `vulns` reads the Go vulnerability database (`vuln.go.dev`, OSV) directly, so `summary` and per-range fix versions are populated (they were empty when sourced from pkg.go.dev). `fixedVersion` is gone — fixed/introduced versions now live in `ranges`; new `aliases`, `packages` and `references` fields are also returned.

| aliases | details | id | ranges | summary |
| --- | --- | --- | --- | --- |
| ["CVE-2020-26160","GHSA-w73w-5m7g-f7qc"] | If a JWT contains an audience claim with an array of strings ... | GO-2020-0017 | [{"introduced":"0.0.0-20150717181359-44718f8a89b0"}] | Authorization bypass in github.com/dgrijalva/jwt-go |

`vulns` returns an empty list when a module has no known vulnerabilities. `--filter` and `--module` no longer apply to `vulns`; only `--version` and `--limit` do.

## dependencies

`godig dependencies github.com/samber/ro -o md` — one section per go.mod block (`requires`, `replaces`, `excludes`, `go` directive):

```markdown
## requires

| path                       | version | indirect |
| -------------------------- | ------- | -------- |
| github.com/samber/lo       | v1.52.0 | —        |
| github.com/davecgh/go-spew | v1.1.1  | true     |
```

## module info

`godig module info github.com/samber/ro -o md`

| field             | value                          |
| ----------------- | ------------------------------ |
| commitTime        | 2026-03-02T15:16:08Z           |
| goVersion         | 1.18                           |
| hasGoMod          | true                           |
| isLatest          | true                           |
| isRedistributable | true                           |
| isStandardLibrary | false                          |
| path              | github.com/samber/ro           |
| repoUrl           | <https://github.com/samber/ro> |
| size              | 137530                         |
| version           | v0.3.0                         |

## packages

`godig packages github.com/samber/ro --limit 4 -o md`

| isRedistributable | name | path | synopsis |
| --- | --- | --- | --- |
| true | ro | github.com/samber/ro | — |
| true | constraints | github.com/samber/ro/internal/constraints | — |
| true | xatomic | github.com/samber/ro/internal/xatomic | — |
| true | xerrors | github.com/samber/ro/internal/xerrors | — |

## symbols

`godig symbols github.com/samber/ro --limit 4 -o md`

| kind     | name              | parent          | synopsis                  |
| -------- | ----------------- | --------------- | ------------------------- |
| Type     | Backpressure      | Backpressure    | type Backpressure int8    |
| Constant | BackpressureBlock | Backpressure    | const BackpressureBlock   |
| Constant | BackpressureDrop  | Backpressure    | const BackpressureDrop    |
| Type     | ConcurrencyMode   | ConcurrencyMode | type ConcurrencyMode int8 |

## symbol doc

`godig symbol doc github.com/samber/lo Map -o md` — token-efficient vs `package doc`:

| field | value |
| --- | --- |
| goarch | all |
| goos | all |
| kind | Function |
| name | Map |
| path | github.com/samber/lo |
| signature | func Map[T, R any](collection []T, transform func(item T, index int) R) []R |
| synopsis | Map manipulates a slice and transforms it to a slice of another type. |
| version | v1.53.0 |

## Raw / large output

`package doc`, `package examples`, `symbol examples` and `module readme` return raw Markdown (use `-o md` or `-o raw`), e.g.:

```markdown
# package ro

## Constants

...
```

`package licenses` and `module licenses` return the full license text.

---
name: golang-pkg-go-dev
description: "Golang package and module lookup via `godig`, a pkg.go.dev API client (CLI + MCP server). Use for any Go/Golang library's documentation, API signatures, symbols, usage examples, which versions exist, licenses, whether a dependency has CVEs, or who imports a package — prefer this over Context7 for any Go package or module. Read-only, no auth. Not for upgrading dependencies (→ See `samber/cc-skills-golang@golang-dependency-management` skill), choosing a library (→ See `samber/cc-skills-golang@golang-popular-libraries` skill), or local symbols and an already-used dependency's resolved source, call sites, and generic instantiations (→ See `samber/cc-skills-golang@golang-gopls` skill)."
user-invocable: true
license: MIT
compatibility: Designed for Claude Code, Codex or similar harness. Requires the godig CLI (go install github.com/samber/godig/cmd/godig@latest) or access to a godig MCP server, and internet access to reach the pkg.go.dev API.
metadata:
  author: samber
  version: "1.4.2"
  openclaw:
    emoji: "🔎"
    homepage: https://github.com/samber/cc-skills-golang
    requires:
      bins:
        - go
        - godig
    install:
      - kind: go
        package: github.com/samber/godig/cmd/godig@latest
        bins: [godig]
    skill-library-version: "0.2.0"
allowed-tools: Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Bash(godig:*) Agent
---

# golang-pkg-go-dev

**Dependencies:** `godig` — `go install github.com/samber/godig/cmd/godig@latest` (or use a registered godig MCP server / the hosted instance instead).

`godig` queries the [pkg.go.dev](https://pkg.go.dev) API. Use it to answer questions about Go packages and modules: docs, symbols, versions, importers and vulnerabilities. It works as a CLI and as an MCP server, and all operations are **read-only** and need no authentication.

## When to use this skill

Trigger on questions like:

- "What versions of github.com/samber/lo are available?"
- "Does golang.org/x/text have known vulnerabilities?"
- "Show me the docs / symbols for package X."
- "Which packages import X?"
- "Search Go packages for Y."

## Choosing between `godig`, gopls, Context7, and govulncheck

In short: `godig` answers questions about the **published ecosystem** (works even for packages not yet in your `go.mod`); `gopls` reasons about **your locally resolved build** (`go.sum`, including `replace`d forks); Context7 is a fallback for non-Go or unindexed docs; `govulncheck` is the whole-tree vulnerability audit (→ `samber/cc-skills-golang@golang-security`). See the `samber/cc-skills-golang@golang-gopls` skill for wiring `gopls` (MCP server, native `LSP` tool, and CLI) with Claude Code, and the `samber/cc-skills-golang@golang-how-to` skill's "`godig` vs gopls vs Context7 vs govulncheck" section for the full task-to-tool matrix.

## Setup

### Install

```bash
go install github.com/samber/godig/cmd/godig@latest
```

### Register the MCP server (optional)

`godig mcp` runs over **stdio** by default, or **streamable HTTP** with `--transport http`. The command is harness-agnostic — any MCP-capable host can point at it. Claude Code registers it via its own CLI:

stdio (the client launches godig on demand):

```bash
claude mcp add pkg-go-dev -- godig mcp
```

streamable HTTP (shared server at `/mcp`, default `:8080`):

```bash
godig mcp --transport http --addr :8080
claude mcp add --transport http pkg-go-dev http://localhost:8080/mcp
```

Hosted instance (no install needed) — a public server runs at `https://godig.samber.dev/mcp`:

```bash
claude mcp add --transport http pkg-go-dev https://godig.samber.dev/mcp
```

Other MCP-capable harnesses (Cursor, Windsurf, and others) each have their own MCP server registration — an entry in their respective settings file pointing at the same `godig mcp` command or hosted URL, not a shared config format.

The CLI and the MCP server expose the **same** operations under matching names. Prefer the CLI when `godig` is installed; the hosted instance is a fallback when it is not.

## Commands

**Global flags (all commands):** `-o/--output table|json|raw|md` (default `table` — pass `-o md` for chat), `--base-url` (pkg.go.dev API), `--vuln-base-url` (Go vulnerability database, consulted by `vulns` and `overview`), `--timeout`, `--log-level debug|info|warn|error|off`. All are also settable via `GODIG_*` env vars.

| Command | Args | Specific flags | Purpose |
| --- | --- | --- | --- |
| `overview` | `<path>` | `--version` | Compact summary (metadata, versions, licenses, vulns) — start here |
| `search` | `<query>` | `--symbol --limit --filter` | Find packages (optionally exporting a symbol) |
| `package info` | `<path>` | `--module --version` | Package metadata |
| `package imports` | `<path>` | `--module --version` | Packages this package imports (plain list) |
| `package doc` | `<path>` | `--module --version --goos --goarch --format md\|text\|html\|markdown` | Full package doc (LARGE) |
| `package examples` | `<path>` | `--module --version --goos --goarch --symbol` | Runnable examples (LARGE; scope with `--symbol`) |
| `package licenses` | `<path>` | `--module --version` | License files, full text (LARGE) |
| `symbol doc` | `<path> <symbol>` | `--module --version --goos --goarch` | One symbol's signature + doc (token-efficient) |
| `symbol examples` | `<path> <symbol>` | `--module --version --goos --goarch` | One symbol's runnable examples |
| `symbols` | `<path>` | `--module --version --goos --goarch --limit --filter` | List exported symbols |
| `module info` | `<path>` | `--version` | Module metadata |
| `module licenses` | `<path>` | `--version` | Module license files (LARGE) |
| `module readme` | `<path>` | `--version` | Module README, full Markdown (LARGE) |
| `dependencies` | `<path>` | `--version` | go.mod deps: requires / replaces / excludes / go directive |
| `packages` | `<path>` | `--version --limit --filter` | Packages contained in a module |
| `versions` | `<path>` | `--limit --filter` | All versions, newest first |
| `major-versions` | `<path>` | `--limit --filter --exclude-pseudo` | Major versions (v1, v2 …) living as separate modules |
| `imported-by` | `<path>` | `--module --version --limit --filter` | Packages that import this one |
| `vulns` | `<path>` | `--version --limit` | Known vulnerabilities (from the Go vuln DB) |
| `mcp` | — | `--transport stdio\|http --addr --cache-ttl --cache-size` | Run as an MCP server |
| `version` | — | — | Print godig version / commit / build date |

When `godig` runs as an MCP server, each data command above is exposed as an operation of the same name.

**Exit codes:** `0` success, `1` runtime error (network, package not found), `2` usage error — a missing/invalid argument or flag (e.g. a non-positive `--limit`), or a command group invoked with no subcommand (`godig package`). Check for `2` to tell a malformed call apart from a failed lookup.

Full `-o md` output for every command: [sample-output.md](references/sample-output.md).

### Tips

- **Start with `overview`** — one call returns a compact summary (metadata, latest + recent versions, license types, vulnerabilities). Reach for `doc`/`examples`/`module readme`/`licenses` (LARGE) only when the full text is needed.
- **Always pass `-o md`** so results render as Markdown (tables, or raw doc/README) in the chat. Other formats exist (`table` default, `json`, `raw`) but prefer `md` here.
- `<path>` is a full import path, e.g. `github.com/samber/lo` — pass it as the positional argument.
- `--version` pins a specific module version (`v1.5.0`, `latest`, `master`, `main`); `--module` disambiguates which module a package belongs to.
- `--filter` narrows list results server-side with a Go boolean expression — see [Filter syntax](#filter-syntax).
- `--goos`/`--goarch` set the documentation/symbols build context (e.g. `linux`/`amd64`).
- Prefer `symbol doc`/`symbol examples` over the package-wide `package doc`/`package examples` when you only need one symbol — far fewer tokens.
- **Parallelize independent lookups** — every command is a self-contained, read-only HTTP query, so calls never depend on each other. When a task needs docs, examples, versions, or vulns for **several** symbols, packages, or modules, issue all the calls at once (multiple `godig` invocations in a single turn) rather than one after another — wall-clock drops from sum-of-latencies to slowest-single-call. For a large fan-out (documenting many symbols, comparing many candidate libraries, auditing CVEs across a dependency set), dispatch up to 5 parallel sub-agents, each running its own `godig` calls and returning a compact summary, so the raw LARGE output never lands in the main context.
- Listing commands auto-paginate (return all results); use `--limit` to cap.

### Filter syntax

`--filter` (on `search`, `versions`, `major-versions`, `packages`, `imported-by`, `symbols`) takes a **Go boolean expression evaluated server-side, once per result item**. It is not a regex — wrap the whole expression in single quotes for the shell.

- **Identifiers are the item's fields, which differ per command** — a field valid for one list is rejected by another (e.g. `search` exposes `packagePath`, not `path`). An unknown field fails with `undefined identifier: <name>` (HTTP 400), which names the offending field. Fields use the item's lowercase JSON key; the exception is enum-like values such as `kind`, which are capitalized (`Function`, not `func`).
- **Operators**: `==` `!=` `<` `<=` `>` `>=`, boolean `&&` `||` `!`, parentheses for grouping.
- **String functions**: `contains(s, sub)`, `hasPrefix(s, pre)`, `hasSuffix(s, suf)`.
- **Literals**: double-quoted strings (`"Function"`), `true`/`false`, numbers.

Filterable fields per command (string unless noted):

| Command | Fields |
| --- | --- |
| `search` | `modulePath`, `packagePath`, `synopsis`, `version` |
| `versions` | `version`, `modulePath`, `deprecated` (bool), `retracted` (bool), `hasGoMod` (bool), `commitTime` |
| `packages` | `path`, `name`, `synopsis`, `isRedistributable` (bool) |
| `imported-by` | `path` (the importing package path) |
| `symbols` | `name`, `kind` (`Function`/`Method`/`Type`/`Variable`/`Constant`), `synopsis`, `parent` |
| `major-versions` | `modulePath`, `major`, `version`, `isLatest` (bool) |

```bash
godig symbols github.com/samber/lo --filter 'kind=="Function"' -o md
godig symbols github.com/samber/lo --filter 'kind=="Function" && hasPrefix(name,"Map")' -o md
godig versions github.com/samber/lo --filter 'hasPrefix(version,"v1.5")' -o md
godig versions github.com/samber/lo --filter 'deprecated==false && retracted==false' -o md
godig search "result option" --filter 'hasPrefix(packagePath,"github.com/samber/")' -o md
```

### Examples

Always request Markdown output (`-o md`):

```bash
# Overview — start here (compact, one call)
godig overview github.com/samber/ro -o md

# Search
godig search "result option monad" --limit 5 -o md

# Package facets
godig package info github.com/samber/ro -o md
godig package imports github.com/samber/ro -o md
godig package doc github.com/samber/ro --format md -o md
godig package examples github.com/samber/ro --symbol Map -o md
godig package licenses github.com/samber/ro -o md

# Single symbol (token-efficient vs package-wide doc/examples)
godig symbol doc github.com/samber/lo Map -o md
godig symbol examples github.com/samber/oops OopsError.Error -o md

# Module facets
godig module info github.com/samber/ro -o md
godig module readme github.com/samber/ro -o raw
godig dependencies github.com/samber/ro -o md

# Lists (auto-paginated; --limit to cap)
godig versions github.com/samber/ro -o md
godig major-versions github.com/samber/lo -o md
godig packages github.com/samber/ro -o md
godig imported-by github.com/samber/ro --limit 20 -o md
godig symbols github.com/samber/ro --filter 'kind=="Function"' -o md

# Pin a version / set the build context
godig versions github.com/samber/ro --filter 'hasPrefix(version,"v0.3")' -o md
godig package doc github.com/samber/lo --version v1.50.0 -o md
godig symbols github.com/samber/ro --goos linux --goarch amd64 -o md

# Vulnerabilities
godig vulns github.com/samber/ro -o md
```

---

This skill is not exhaustive. `godig --help` and each sub-command's `--help` list current flags and output formats; the data mirrors what [pkg.go.dev](https://pkg.go.dev) exposes.

If you encounter a bug or unexpected behavior in `godig`, open an issue at <https://github.com/samber/godig/issues>.