fontina0.2.0

Next: Concepts,  Up: Manual

1. Getting started

install, index your fonts, and ask the first questions.

Installing

Get a release binary from the download page and put it on your PATH, or build it with Rust 1.88 or newer:

cargo install --git https://github.com/oddurs/fontina fontina-cli

Check that it runs:

$ fontina --version
fontina 0.0.1

Indexing

Run fontina on its own and it tells you where you stand. On a new install that is nothing yet, and it says where this machine keeps fonts and what to type:

$ fontina
No fonts indexed yet.

This machine keeps fonts in:
  ~/Library/Fonts
  /Library/Fonts
  /System/Library/Fonts

To index them:
  fontina scan --system    the operating system's own directories
  fontina scan ~/Fonts     a directory of your own

It suggests and never runs: nothing scans your disk until you ask it to.

fontina keeps what it learns about your fonts in an index, a single SQLite file in the platform data directory (see The index and paths). The index starts empty. Fill it by scanning:

$ fontina scan --system
934 faces in 395 families · 321 free
largest: JetBrainsMono Nerd Font 16 · Noto Sans 12 · Iosevka 9
scanned 518 candidates in 14.07s: 517 parsed (934 faces), 0 unchanged, 0 removed, 1 failed

The first scan leads with what you have; a rescan is just the ledger, because by then you know. Afterwards, fontina on its own is the shape of the library and the two or three things worth doing next.

A scan walks the directories, parses every font file it finds, and records one face per font. A rescan is fast: files whose size and modification time have not changed are skipped. Use --prune to drop entries for files that have gone, and --force to re-parse everything, which is needed after upgrading to a version of fontina that extracts more.

If you want a directory rescanned in future without naming it every time, register it as a source instead:

$ fontina source add ~/Fonts

Looking

list prints every face in the index, one line each:

$ fontina list
    id  family               style           wght  wdth  flags  license       path
     1  Amiri                Regular          400   100  ----   OFL-1.1       /home/me/Fonts/Amiri-Regular.ttf
     2  Bricolage Grotesque  96pt ExtraBold   800   100  V---   OFL-1.1       /home/me/Fonts/BricolageGrotesque[opsz,wdth,wght].ttf
     3  Nabla                Regular          400   100  VC--   OFL-1.1       /home/me/Fonts/Nabla[EDPT,EHLT].ttf
     4  Source Serif 4       Regular          400   100  ----   OFL-1.1       /home/me/Fonts/SourceSerif4-Regular.otf
4 face(s)

The id column is the face’s number in the index; most commands accept it. The flags are V for variable, C for colour, I for italic and A for active.

Filters narrow the list. They combine, and every one also applies to families and facets:

$ fontina list --script Arab          # faces whose cmap covers Arabic
$ fontina list --variable             # variable fonts
$ fontina list --license OFL          # by SPDX identifier prefix
$ fontina list --weight 600-900       # by CSS font-weight range
$ fontina list --vendor ADBE          # by OS/2 vendor id
$ fontina list grotesque              # full-text search over names and designer

info prints everything known about one face. It takes an id, or a path to any font file, indexed or not:

$ fontina info 2
$ fontina info ~/Downloads/Mystery.ttf

facets shows the shape of the whole collection, or of any filtered subset:

$ fontina facets
6 face(s) in 5 family(ies)
weight      400 Regular 5 · 800 ExtraBold 1
width       100% Normal 6
style       upright 6
variable    2   color 1
container   ttf 3 · otf 1 · woff 1 · woff2 1
script      Latn 6 · Zinh 6 · Zyyy 6 · Grek 2 · Arab 1 · Cyrl 1
license     OFL-1.1 6
vendor      RSMS 2 · ADBO 1 · ALIF 1 · ATLR 1 · TYPT 1
activation  none 6
source      /home/me/Fonts 6

Asking

Which fonts can set this text?

$ fontina covers "Þórður át 12 blóðbergsbrauð"

Which files are the same font twice?

$ fontina dupes

Is this font sound?

$ fontina check ~/Fonts/*.ttf
PASS  Amiri Regular  (/home/me/Fonts/Amiri-Regular.ttf#0)  0 error(s), 0 warning(s)
1 face(s) checked, 0 failed

May I embed it?

$ fontina license 1
OFL-1.1  (1 face(s))
  Amiri Regular  [Installable]  /home/me/Fonts/Amiri-Regular.ttf

Seeing

preview draws a face as real, shaped glyphs in the terminal, as an image where the terminal supports one and as half-block text everywhere else:

$ fontina preview 2 -t "Sphinx of black quartz" -a wght=700

ui opens a full-screen browser over the index, with facets, families, details and previews, driven from the keyboard:

$ fontina ui

Activating

Indexing tells fontina about a font. Activating tells the operating system, per user, in place, so every application can use it:

$ fontina activate family:Amiri
$ fontina activate 2 --session      # until logout
$ fontina activations
$ fontina deactivate family:Amiri

install copies a font into the per-user font directory instead. Both refuse, with exit status 2, when another active font has the same name; conflicts shows why and --replace overrides. See Activation and installation.

Exporting

css writes @font-face rules, with a URL prefix of your choosing instead of file paths:

$ fontina css 1 2 --url-prefix /fonts/ > fonts.css

specimen writes a self-contained HTML page with a waterfall, script samples, axis sliders, feature toggles, a glyph map and side-by-side comparison. It embeds the font files, so it works from disk with no server:

$ fontina specimen 1 2 3 -o specimen.html

Every command takes --json for machine-readable output; see JSON output and schemas.

Where to go next

Next: Concepts,  Up: Manual