Next: JSON output and schemas,  Previous: Watching, previews and the browser,  Up: Manual

5. Command reference

fontina(1), in the form of a man page.

This chapter follows the layout of a manual page. fontina help <command> prints the same information from the binary itself, and is always current for the version you have.

NAME

fontina: scan, search, inspect, preview, activate, check and export fonts.

SYNOPSIS

fontina [--db PATH] <command> [options] [arguments]

DESCRIPTION

fontina indexes font files into a SQLite database and answers questions about them. The index is a single file; --db or the FONTINA_DB environment variable selects it, otherwise it lives in the platform data directory. Every command that prints a report accepts --json; the output types are published in schemas/cli-output.json.

A target argument is a face id from list, a path to a font file, or, for commands that act on a set of faces, family:<name>. A path may carry the face index a listing prints after it, path#1, which names one face of a font collection; the path on its own means every face in the file.

Exit status is 0 on success, 1 on error, and 2 when a conflict blocked an activation and nothing was applied.

Output is written for whoever is reading it. At a terminal, tables are fitted to the window and coloured — the label, the count and the directory part of a path recede so that the family name and the filename stand out, and a failing check is red because that is how you find it, not how you know: it says FAIL either way. Piped, none of that happens. No escape is ever written to something that is not a terminal, and the columns are not re-fitted either, because a script that cuts a field out of fontina list can wrap a long line and cannot un-truncate a short one.

COMMANDS

Indexing

scan [PATHS]... [--system] [--force] [--follow-symlinks] [--prune] [--json]

Index fonts under one or more directories or files. --system adds the operating system's font directories. Unchanged files (same size and modification time) are skipped unless --force. --prune drops index entries under the scanned roots whose files no longer exist. Symlinks are not followed unless asked.

source list

The directories the index was built from, with face counts and whether they are watched.

source add PATH [--no-watch] [--json]

Register a directory and scan it now. It is followed by watch unless --no-watch.

source remove PATH [--purge]

Forget a directory. With --purge, drop its faces from the index too.

source watch PATH [--off]

Turn watching on (the default) or off for a source.

stats [--json]

Index statistics: files, faces, families, variable and colour counts, failures, tags, collections, sources, active faces; and the most recent parse failures.

dirs [--json]

Print the operating system's font directories, marking the per-user one.

Querying

The three query commands share one set of filters, listed under FILTERS.

list [QUERY] [filters] [-n LIMIT] [--json]

List indexed faces, one per line: id, family, style, weight, width, flags, license, path. QUERY is a full-text search over family, style, PostScript name and designer.

families [QUERY] [filters] [-n LIMIT] [--json]

The same faces grouped by typographic family name.

counts [QUERY] [filters] [--json]

Count the matching faces per weight, width, style, script, license, vendor, tag, collection, activation state and source.

info TARGET [--json]

Everything known about one face. A path that is not indexed is parsed on the spot.

covers TEXT [--variable] [--under PREFIX] [-n LIMIT] [--json]

Faces whose character map covers every character of TEXT.

glyphs TARGET [--block NAME] [--json]

A face's character coverage by Unicode block. --block prints the characters of one block, matched by case-insensitive substring of its name.

duplicates [--json]

Faces that are the same font in several containers, and faces that share a PostScript name.

Organising

tag list

All tags with their face counts.

tag add TAG TARGETS...

Add a tag to faces; the tag is created if new.

tag remove TAG TARGETS...

Remove a tag from faces.

tag rename OLD NEW, tag delete TAG

Rename a tag everywhere; delete it from every face.

collection list

All collections with their face counts.

collection create NAME, collection delete NAME, collection rename OLD NEW

Manage collections by name.

collection add NAME TARGETS...

Append faces to a collection, creating it if missing.

collection remove NAME TARGETS...

Remove faces from a collection.

collection show NAME

The faces of a collection, in order.

collection export NAME [OUTPUT]

Write a collection as JSON conforming to schemas/collection.json. OUTPUT defaults to standard output.

collection import FILE

Read a collection JSON file into this index, matching faces by identity hash, then PostScript name, then path.

Activating

See Activation and installation.

activate TARGETS... [--session] [--replace] [--json]

Make faces visible to other applications, in place. Persistent for the user unless --session, which lasts until logout. Exit status 2 when a conflict blocks it; --replace first deactivates or uninstalls the conflicting faces that fontina manages.

deactivate TARGETS... [--json]

Undo activate.

install TARGETS... [--replace] [--json]

Copy faces into the per-user font directory. Exit status 2 on an unresolved conflict.

uninstall TARGETS... [--json]

Remove the per-user copies made by install.

conflicts TARGETS... [--json]

Faces that would clash with these once active: same PostScript name, or same family and style, already active or living in an operating-system font directory.

activations [--json]

Everything fontina has activated or installed, with state and time.

restore [--json]

Re-apply recorded activations, for a login agent or after a reboot. Idempotent.

Watching

watch [PATHS]... [--debounce-ms MS] [--json]

Follow the watched sources, and any extra directories given, and keep the index current until interrupted. Changes are applied in batches after a quiet period (default 500 ms); one line per batch, or one JSON object per line. See Watching, previews and the browser.

Previewing

preview TARGETS... [-t TEXT] [-s SIZE] [-a AXIS=VALUE]... [-f FEATURE[=0]]... [-p PROTOCOL] [-o FILE] [--fg RGB] [--bg RGB] [--max-width PX]

Draw faces as real, shaped glyphs in the terminal, using kitty graphics, iTerm2 images, sixel, or half-block text, whichever the terminal supports (-p forces one). -o writes a PNG of one face instead. -s is the size in pixels (default 48); -t the sample text, \n for a new line.

ui

The keyboard-first browser over the index: facets, families, faces, details and previews. ? inside it lists the keys.

Shell

completions SHELL

Print completions for bash, zsh, fish, elvish or powershell. Release archives carry them too.

man [--out-dir DIR]

Print the man page, or write fontina.1, fontina-scan.1 and one page per command into a directory.

Checking

check [TARGETS]... [--strict] [--min LEVEL] [--json]

Run health checks. Findings are info, warn or error; --min hides those below a level. The exit status is 1 if any check reports an error, or with --strict, a warning. See Health checks.

license [TARGETS]... [--json]

License and embedding report: SPDX identifier, embedding rights from fsType, and reserved font names. Covers every indexed face when no target is given.

Exporting

css [TARGETS]... [--url-prefix PREFIX]

Emit one @font-face rule per face with font-weight, font-stretch, font-style, font-display: swap, src with the right format(), and unicode-range from the character map. Without --url-prefix the sources are file:// paths.

specimen [TARGETS]... [-o FILE] [--text TEXT] [--title TITLE] [--link]

Write a self-contained HTML specimen: waterfall, script samples, axis sliders, feature toggles, glyph map, and side-by-side comparison of several faces. Fonts are embedded unless --link, which references them by path and needs an HTTP server or a browser that allows file:// font loads. See Specimens.

config [--path] [--example] [--json]

Show every setting in force and where it came from: a flag, the environment, the configuration file, or fontina's own default. --path prints the file's location; --example prints a commented file holding every setting, to save there and edit. See The index and paths.

schema [face|collection|cli-output]

Print one of the JSON Schemas. face is the default.

FILTERS

Accepted by list, families and counts; all of them combine.

OPTIONS

--db PATH

Path to the index database. Defaults to FONTINA_DB, then the platform data directory.

--json

Machine-readable output. Available on every reporting command.

-h, --help, -V, --version

As usual.

ENVIRONMENT

FONTINA_DB

Path of the index database when --db is not given. Outranks index.db in the configuration file.

FONTINA_CONFIG

Path of the configuration file, instead of the one in the platform configuration directory.

XDG_DATA_HOME, XDG_CONFIG_HOME

Honoured on Linux for the default index location and, in future, configuration.

NO_COLOR

Set to anything: never colour, whatever else says. There is no --color flag because --color is already a filter — fontina list --color is the fonts that carry their own colour.

CLICOLOR_FORCE

Set to anything but 0: colour even when the output is not a terminal, for a pager that understands escapes.

COLUMNS

How wide to print, instead of what the terminal reports. Read only when the output is a terminal.

TERM, COLORTERM

How much colour the terminal can show. TERM=dumb is a terminal saying it cannot, which is what NO_COLOR says from the other direction.

FILES

See The index and paths.

EXIT STATUS

0 on success. 1 on any error, including a check that reports an error (or a warning with --strict). 2 when activate or install found a conflict and applied nothing. Parse failures during scan are counted and reported but do not fail the scan.

EXAMPLES

Index the system fonts and your own, then look for a Cyrillic serif:

fontina scan --system ~/Fonts
fontina list --script Cyrl serif

Everything that is not under an open license:

fontina list --license LicenseRef

The bold weights of one family as CSS for a web project:

fontina css $(fontina list --family "Source Serif 4" --weight 600-900 --json | jq '.[].id') --url-prefix /fonts/

A specimen comparing three candidates:

fontina specimen 12 34 56 --text "Hamburgefonstiv" -o compare.html

Fail a build if any shipped font has an error:

fontina check dist/fonts/* --min warn

Activate a family for this session, look at it, and let it go at logout:

fontina activate family:Amiri --session
fontina preview family:Amiri -t "بسم الله الرحمن الرحيم"

Install the completions for zsh:

fontina completions zsh > ~/.zfunc/_fontina

SEE ALSO

fontina man for the same reference from the binary. fc-list(1), fc-query(1), fc-cache(1), fonttools’ ttx(1). The architecture decision records.

OLD NAMES

Two commands were renamed to what somebody would guess rather than what the code called them. Both old spellings still run, and always will: a script written against 1.0 has to run against 3.0.

Next: JSON output and schemas,  Previous: Watching, previews and the browser,  Up: Manual