CLI commands

Global option

Flag	Effect
`--refresh-cache`	Ignore a valid local catalog cache and download a fresh list from GWFH (works on any subcommand).

Caching

Path: ~/.gfcli/cache.json
TTL: 24 hours from the timestamp stored in the file.
Payload: JSON with fetchedAt (milliseconds) and fonts (array of raw GWFH font objects). If the file is missing, invalid, or expired, the next command downloads the list again and rewrites the cache.

While the cache is valid, commands avoid re-downloading the full catalog (faster startup).

Performance

Prefer --woff2 for assets you ship on the web; files are much smaller than TTF.
Pass -v with only the weights you need (e.g. regular,700) to save bandwidth and disk space.

`gfcli search [family...]`

Fuzzy search on family name. Matching is case-insensitive; every word in the query must appear somewhere in the family string, in any order (sans source and source sans match the same families).

gfcli search source

Arguments are joined with spaces before search.

`gfcli download <family...>`

Resolves each family to exactly one catalog entry. If the string matches zero or several families, nothing is downloaded and the CLI prints close matches (same as search output).

Option	Description
`-d`, `--dest <folder>`	Output directory. If omitted: current working directory, or the user home directory if cwd is not writable.
`-v`, `--variants <list>`	Comma-separated variant ids (`300`, `regular`, `700italic`, …). Omit to fetch all variants that GWFH exposes for that format.
`--ttf`	TTF (default).
`--woff2`	WOFF2.

Several families in one go: use a comma-separated list inside quotes so the shell does not split them: "Inter,Roboto".

gfcli download "Inter,Roboto" --woff2 -d ./fonts

`gfcli install <family...>`

Installs TTF variants into the OS user font location:

Linux: ~/.local/share/fonts/
macOS: ~/Library/Fonts/
Windows: native registration (not a raw copy only into C:\Windows\Fonts)

Same single-match rule as download. Options:

Option	Description
`-v`, `--variants <list>`	Comma-separated variants; omit for all available TTF variants.

gfcli install "Inter,Roboto" -v regular,700

`gfcli copy <family...>`

Requires one unambiguous family. Copies a Google Fonts CSS URL to the clipboard (via copy-paste-win32fix).

Base URL shape: https://fonts.googleapis.com/css?family=Family+Name. With -v, the CLI appends :variant1,variant2 to that URL.

gfcli copy "work sans" -v 200,400,600

Exit codes

For download and install, if every requested family fails, the process exits with a non-zero code. If at least one family succeeds, exit code is 0 and any failures are summarized on the console.