@liiift-studio/vf-clamp-cli

A command-line interface for @liiift-studio/vf-clamp — restrict variable font axis ranges from the terminal without writing any JavaScript.

Install

Requires Node.js 18 or newer.

npm install -g @liiift-studio/vf-clamp-cli

Discovery

vf-clamp --help              # top-level overview, both subcommands
vf-clamp --version           # also: -v
vf-clamp clamp --help        # subcommand-specific help, examples, axis spec guide
vf-clamp instances --help

Usage

Inspect a font

List all variable axes and named instances in a font file (TTF, OTF, WOFF, or WOFF2):

vf-clamp instances MyFont.ttf
vf-clamp instances MyFont.ttf --json     # machine-readable

Example output (exact column spacing depends on your font):

Axes:
  wght  Weight     100 → 900  (default: 400)
  slnt  Slant      -10 → 0    (default: 0)

Instances (18):
  Thin              wght=100 slnt=0
  ExtraLight        wght=200 slnt=0
  Light             wght=300 slnt=0
  Regular           wght=400 slnt=0
  Medium            wght=500 slnt=0
  SemiBold          wght=600 slnt=0
  Bold              wght=700 slnt=0
  ...

Clamp a font

Produce a restricted VF spanning the hull of named instances:

vf-clamp clamp MyFont.ttf --instance Light --instance Bold --name Light-Bold

Short flags are accepted for every option:

vf-clamp clamp MyFont.ttf -i Light -i Bold -n Light-Bold

Restrict using explicit axis ranges:

vf-clamp clamp MyFont.ttf -a wght:300:700 -n Custom -f woff2

Pin a single axis value, or keep an axis at its full original range:

vf-clamp clamp MyFont.ttf -a wght:400 -n Regular-Only
vf-clamp clamp MyFont.ttf -i Light -i Bold -a wdth:*       # keep wdth untouched

Combine instances and axis overrides:

vf-clamp clamp MyFont.ttf -i Light -i Bold -a slnt:-5:0 -n LightBold-Slanted

Read source font from stdin and pipe results:

cat MyFont.ttf | vf-clamp clamp - -i Bold -n Bold-only -o ./out

Write output to a specific directory:

vf-clamp clamp MyFont.ttf -i Light -i Bold -o ./dist/fonts

When --name is omitted, the output filename is derived from the instance names (Light-Bold) or axis tags. All names are sanitised for filesystem safety: characters like /, \, :, .., ASCII control codes, and Windows reserved device names are stripped or rejected.

Clamp using a config file

For multiple outputs in one pass, use a JSON config file. All outputs are produced in a single engine invocation — the font is parsed once, not N times.

vf-clamp clamp MyFont.ttf -c clamp.config.json

clamp.config.json:

{
  "format": "ttf",
  "outputDir": "./output",
  "outputs": [
    {
      "name": "Light-Bold",
      "instances": ["Light", "Bold"]
    },
    {
      "name": "Condensed",
      "axes": { "wdth": { "min": 50, "max": 75 } }
    },
    {
      "name": "WeightRange-KeepWidth",
      "axes": { "wght": { "min": 100, "max": 700 }, "wdth": null }
    }
  ]
}

Each output must specify either instances, axes (non-empty), or both. Axis values may be a number (pin), { "min": …, "max": … } (range), or null (keep full original range).

CLI flags --instance, --axis, and --name are ignored when --config is used; a warning is printed to stderr.

Options

vf-clamp instances <font>

Argument / Option	Description
<font>	Path to TTF, OTF, WOFF, or WOFF2 file (or - for stdin)
--json	Print results as JSON to stdout
-q, --quiet	Suppress progress messages on stderr
--verbose	Print Python tracebacks on engine errors

vf-clamp clamp <font> [options]

Option	Description
<font>	Path to TTF, OTF, WOFF, or WOFF2 file (or - for stdin)
-i, --instance <name>	Named instance to include (repeatable)
-a, --axis <tag:value>	Pin an axis to a fixed value
-a, --axis <tag:min:max>	Restrict an axis to a range
-a, --axis <tag:*> (or tag:keep)	Keep axis at its full original range
-n, --name <name>	Output name (filename stem; sanitised for filesystem safety)
-f, --format <fmt>	Output format: ttf (default), otf, woff, woff2
-o, --output <dir>	Output directory (default: current directory)
-c, --config <file>	JSON config file (for multiple outputs)
--no-force	Refuse to overwrite existing output files
--dry-run	Validate inputs without invoking the engine or writing files
--json	Print results as JSON to stdout
-q, --quiet	Suppress progress messages on stderr
--verbose	Print Python tracebacks on engine errors

Output and exit codes

For scripting, output paths are written one-per-line to stdout; all progress and error messages go to stderr:

vf-clamp clamp MyFont.ttf -i Light -i Bold | xargs -n1 woff2_compress

Exit codes follow BSD sysexits conventions:

Code	Meaning
0	Success
2	Usage / validation error (bad flags, malformed --axis, missing inputs)
65	Input data error (bad font, bad JSON config)
66	Input file missing or unreadable
70	Internal engine error
78	Invalid configuration
130	Aborted by Ctrl-C (SIGINT)

Performance Note

The underlying engine uses Pyodide (Python WASM). The first run in a process takes approximately 10–20 seconds to initialise. Subsequent calls in the same process are 1–2 seconds. This is expected — plan config-file batching for large workflows so the engine pays cold-start only once.

Related

• @liiift-studio/vf-clamp — the core library
• vfclamp.com — web interface

License

MIT © Liiift Studio