gleamdoc

Sparse, terminal-first documentation lookup for Gleam packages, inspired by zigdoc.

Gleamdoc reads compiler-generated package interfaces for the current project and all locally downloaded dependencies. It supports exact public symbol lookup, including custom type variants, package-qualified lookup, ranked text and signature search, source locations, and machine-readable JSON output.

gleamdoc gleam/list

gleamdoc gleam/list.map

gleamdoc gleam_stdlib:gleam/list.map

gleamdoc search "decode json"

gleamdoc packages

gleamdoc index

gleamdoc --version

Queries use <module>.<symbol> for values, types, and custom type variants. An exact module name lists that module's public members. Prefix a query with <package>: when two dependencies expose the same module name.

Signatures fully qualify non-prelude named types as <package>:<module>.<type>. Prelude types such as String, List, and Result retain their short names.

Flags

gleamdoc gleam/list.map --json

gleamdoc gleam/list.map --package=gleam_stdlib

gleamdoc gleamdoc/interface.lookup --no-deps

gleamdoc search map --limit=10

gleamdoc search decode --package=gleam_json --json

gleamdoc search decode --kind=fn

gleamdoc search external --target=erlang

gleamdoc packages --no-deps

gleamdoc index --package=gleam_json

gleamdoc index --no-deps

Run gleamdoc index after downloading or changing dependencies, or after changing the current project's public interface. Lookup, search, and package listing commands only read validated files under build/gleamdoc; they do not run the Gleam compiler or dependency resolver. A missing or stale cache is an error that tells you to run the index command.

gleamdoc index --no-deps only indexes the current project. gleamdoc index --package=NAME indexes the current project and the selected dependency. Package-qualified lookups and --package=NAME searches likewise load only that dependency's cache.

Successful commands exit with status 0. Invalid arguments, indexing failures, unknown packages, missing symbols, and empty searches exit with status 1.

Human-readable output uses color when written to a terminal. Set NO_COLOR or redirect the output to disable ANSI styling.

JSON output is wrapped in an envelope with "schema_version": 1 and a "results" array. Errors use the same envelope and include an "error" field.

An example agent guide for new Gleam projects is available at templates/AGENTS.md. It documents a Gleam workflow that uses Gleamdoc for API discovery.

Lookup output includes the source file and declaration line when the package's source is available locally:

source: build/packages/gleam_stdlib/src/gleam/list.gleam:352

Search uses weighted ranking. Exact symbol names rank first, followed by name prefixes and partial names, module matches, signature matches, and finally documentation matches. All query terms must match somewhere in the package-qualified name, signature, or documentation.

Dependency interfaces are generated by gleamdoc index from the packages already present in build/packages. The indexer stages each package with the project's locked manifest and local package directory, then runs gleam export package-interface. Interfaces are cached under build/gleamdoc/packages and regenerated when package source or configuration changes. Temporary staging directories are removed when indexing finishes or fails.

With a valid manifest.toml and populated build/packages, dependency exports can run using those local files. Unlike normal query commands, however, gleamdoc index invokes the Gleam build tool, so any dependency resolution or download behavior is controlled by the installed Gleam version.

Install

Build a standalone Erlang escript:

make build

./gleamdoc gleam/list.map

Install it to ~/.local/bin:

make install

Use PREFIX or BINDIR to choose another location:

make install PREFIX=/usr/local

make install BINDIR="$HOME/bin"

Development

gleam run -- --help

make test

The small process-launch and exit-status FFI boundary currently targets Erlang. Indexing, cache validation, staging, and source lookup are implemented in Gleam.