@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