Troubleshooting
Permission denied (EACCES) when installing
Section titled “Permission denied (EACCES) when installing”- Linux / macOS: Your user must be able to write the font directory (
~/.local/share/fontsor~/Library/Fonts). Fix directory ownership or permissions. - Windows: Run the terminal as Administrator when installing fonts.
No results or “unable to find font family”
Section titled “No results or “unable to find font family””- Check spelling; names must match the catalog (use
gfcli search partialname). - If several families match your string, the CLI lists them; pick the exact family name and retry.
- Refresh the catalog:
gfcli search yourterm --refresh-cache
“Failed to download font list” or stale catalog
Section titled ““Failed to download font list” or stale catalog”- Confirm network access to
gwfh.mranftl.com. - Run any command with
--refresh-cacheto ignore~/.gfcli/cache.jsonand fetch a new list. - You can delete
~/.gfcli/cache.jsonmanually to force a cold start.
Clipboard / copy does nothing useful
Section titled “Clipboard / copy does nothing useful”gfcli copyneeds a single exact family match; otherwise it prints alternatives likedownload/install.- On headless or remote SSH sessions, clipboard integration may not exist; use
getCssUrl()from the Node API instead.
WOFF2 requested but files missing
Section titled “WOFF2 requested but files missing”GWFH does not always publish WOFF2 for every variant. If a variant has no WOFF2 URL, that variant is skipped when building the file map. Try TTF or a different variant set.
Using this from another Node.js project
Section titled “Using this from another Node.js project”Install google-font-cli as a dependency and require('google-font-cli'). See Node module & API.