# CLI reference (https://static-to-variable.blode.md/cli-reference)

Every command, flag, and exit code.

## Commands

```bash
static-to-variable init          # detect fonts, write ./stv.config.json
static-to-variable build         # rebuild -> normalize -> build
static-to-variable release       # finalize + WOFF2
static-to-variable split <font>  # variable font -> static weights (the reverse)
static-to-variable doctor        # environment readiness
static-to-variable --version
static-to-variable --help
```

`build` and `release` read `./stv.config.json` by default. Pass `--config <path>` to use another.

## Split a variable font back into static weights

`split` is the reverse of `build`: it pins the font at each step along its `wght` axis and writes one static TTF + WOFF2 per weight, each named so they install side by side. No config needed. Any other axes are pinned to their default.

```bash
static-to-variable split MyFamily-VF.ttf            # -> ./static/*.ttf + *.woff2
static-to-variable split MyFamily-VF.ttf --out dist # choose the output directory
static-to-variable split MyFamily-VF.ttf --step 50  # finer weight steps (default 100)
```

## Conventions

- `build`, `release`, `split`, and `doctor` take `--json` for a machine-readable summary on stdout. Human progress always goes to stderr, so piped stdout stays clean.
- Configs are validated against `schemas/stv-config.schema.json` before any engine work starts. Violations name the offending path.
- Errors carry a stable `STV_*` code and a suggested fix. `NO_COLOR` is respected on both streams.

## Exit codes

| Code  | Meaning                                           |
| ----- | ------------------------------------------------- |
| `0`   | Success                                           |
| `1`   | Failure                                           |
| `2`   | Usage error (bad flag, missing or invalid config) |
| `3`   | Environment error                                 |
| `130` | Interrupted                                       |

## Configuration

Everything font-specific lives in `stv.config.json` (schema v3): family metadata, axes and named instances, per-style donors and masters, vertical metrics, per-glyph repair strategies, and output paths. See the [schema](https://github.com/mblode/static-to-variable/blob/main/schemas/stv-config.schema.json) and the worked [Inter example](https://github.com/mblode/static-to-variable/tree/main/examples/inter).

# Overview (https://static-to-variable.blode.md/)

Turn separate font weight files into one variable font.

# static-to-variable

Got a font as thin, regular, and bold files? Point this at them and get back one file you can slide between.

You can't just merge the files, because each weight is drawn separately and nothing lines up. static-to-variable redraws them onto one shared structure so they blend, checks every letter, and skips anything it can't convert cleanly instead of breaking it.

## Try it in the browser

Head to [variable.blode.co](https://variable.blode.co): drop your fonts in and build right in the browser, or explore demos built from Google Fonts that never had a variable version.

## Install

```bash
npm install -g static-to-variable
```

Needs [Node](https://nodejs.org) 24.11+, [Python](https://www.python.org) 3.11+, and [uv](https://docs.astral.sh/uv/). The font engine sets itself up the first time you build.

## Next steps

- [Quickstart](quickstart) — go from separate weights to one variable font.
- [CLI reference](cli-reference) — every command, flag, and exit code.

# Quickstart (https://static-to-variable.blode.md/quickstart)

Go from separate weights to one variable font.

## 1. Point it at your fonts

Go to a folder with your font files and run:

```bash
static-to-variable init
```

It finds your fonts, reads their weights, and writes an `stv.config.json` for you. Confirm the list and name the family. In a non-interactive shell (CI, agents) it writes a starter template to edit instead.

## 2. Build

```bash
static-to-variable build
```

Your variable font lands in `build/`. When you're happy with it, write the final TTF and WOFF2:

```bash
static-to-variable release
```

## Going the other way

Already have a variable font and want the individual weights? `split` runs it in reverse: one static TTF + WOFF2 per weight, in `static/`.

```bash
static-to-variable split MyFamily-VF.ttf
```

## If anything complains

Run the environment check. It verifies Node, Python, uv, and your config, then tells you what to fix.

```bash
static-to-variable doctor
```