google-fonts-search

Search and query the Google Fonts metadata corpus — from the command line or as a library. The full dataset (~2,000 families, their fonts, variable axes, subsets, languages, and tag scores) is bundled as a single JSON file, so there's nothing to download or compile and just one tiny dependency (the TOON encoder, used for CLI output).

CLI

No install needed — run it straight from npm:

npx google-fonts-search@latest <command> [args] [options]

npx google-fonts-search@latest family roboto

The @latest tag tells npx to always fetch the current published version (skipping any stale cached copy). Run npx google-fonts-search@latest --help for the full command list.

Output format

Output defaults to TOON (Token-Oriented Object Notation — compact and token-efficient, ideal for piping into LLMs). Override per command:

Flag	Format
(default) / --toon	TOON
--json	JSON (pretty-printed)
--table	Human-friendly tables + a rich family detail view

npx google-fonts-search@latest variable wght            # TOON
npx google-fonts-search@latest variable wght --json     # JSON
npx google-fonts-search@latest family roboto --table    # human detail view

Result limit

List commands return at most 20 results by default. Override with the global --limit <n> (or -n <n>) flag:

npx google-fonts-search@latest category SANS_SERIF --limit 50
npx google-fonts-search@latest tag /Expressive/Calm -n 5

Commands

Command	Description
search <text>	Search families by name
family <slug|name>	Full detail for one family (fonts, axes, subsets, top tags)
category <CAT>	Families in a category (SANS_SERIF SERIF DISPLAY HANDWRITING MONOSPACE)
subset <subset>	Families supporting a subset (e.g. cyrillic)
language <prefix>	Families supporting a language (e.g. ja, en_Latn)
variable [axisTag]	Variable families; optionally filter by axis (wght wdth slnt opsz …)
designer <name>	Families by designer (substring match)
tag <path> [minScore]	Families by tag path (e.g. /Expressive/Calm), score-sorted
tags	Every distinct tag path, with family counts
filter [criteria]	Ranked shortlist matching ALL criteria — --tag (repeatable), --category, --subset, --variable, --axis, --min. Built for picking a font for a design direction
stats	Dataset summary
info	Dataset provenance (source commit, build date)

Examples:

npx google-fonts-search@latest variable wght
npx google-fonts-search@latest tag /Expressive/Calm 70
npx google-fonts-search@latest category MONOSPACE

Library

npm install google-fonts-search

import { getFamily, familiesByTag, families, meta } from "google-fonts-search";

getFamily("roboto");                 // full family object, or null
familiesByTag("/Expressive/Calm", 70); // [{ slug, name, tag, axis, score }]
families.length;                      // 2016 — the raw dataset array
meta.fontsCommit;                     // source commit the snapshot was built from

All query functions operate on the in-memory dataset (loaded once, lazily). Exported functions: searchFamilies, getFamily, familiesByCategory, familiesBySubset, familiesByLanguage, variableFamilies, familiesByDesigner, familiesByTag, listTags, stats. Also exported: families, meta, the bySlug / byName index maps, and the Family / Font / Axis / Tag types.

Agent skill

The repo ships a Claude Code skill at skills/google-fonts-search/SKILL.md that teaches an agent to pick fonts deliberately for a design — list the style-tag vocabulary, choose tags that match the brief, then filter to a ranked shortlist — instead of defaulting to the usual handful of popular families. It also covers the everyday lookups (by category, script, language, designer, axis).

Install with skills.sh

The skills CLI installs it straight from this GitHub repo:

# Into the current project (./.claude/skills/)
npx skills add phelma/google-fonts-data --skill google-fonts-search

# Or globally, for every project (~/.claude/skills/)
npx skills add -g phelma/google-fonts-data --skill google-fonts-search

Install manually

Or copy the SKILL.md into a directory Claude Code discovers:

mkdir -p ~/.claude/skills/google-fonts-search
curl -fsSL https://raw.githubusercontent.com/phelma/google-fonts-data/main/skills/google-fonts-search/SKILL.md \
  -o ~/.claude/skills/google-fonts-search/SKILL.md

The skill only documents the npx google-fonts-search@latest CLI, so there's nothing else to install — the agent runs the published package on demand.

How it's built

data/families.json is generated from a local checkout of the google/fonts repo:

bun run build:data   # parse fonts/ -> data/families.json
bun run build        # tsc -> dist/ (JS + .d.ts)

• src/textproto.ts — minimal protobuf-text-format parser for METADATA.pb (nested messages, repeated fields, # comments, adjacent-string concatenation).
• scripts/build-data.ts — scans every METADATA.pb plus tags/all/families.csv and emits the bundled JSON with provenance.
• src/queries.ts — the query functions.
• src/cli.ts — CLI entrypoint.

Notes

• The data is a snapshot baked at publish time. Run info to see which google/fonts commit it was built from. Refresh = pull new fonts, re-run build:data, republish.
• The tags CSV references families by display name; ~8 names (105 rows) are stale/renamed or not present in the source (e.g. Google Sans) and are skipped at build time.
• Families with no languages field in their metadata (e.g. Roboto) simply have an empty languages array.