Skip to content

ftCLI wizard

ftCLI edited this page May 4, 2021 · 24 revisions

The ftcli wizard command helps to automatically calculate namerecords in the the name table and set proper values for usWidthClass, usWeightClass, bold and italic bits.

The process consists in creating a CSV file that contains, for each file of the family, the desired values: italic bits set or clear (0/1), usWidthClass value and relative long and short style names (e.g. 3, Cn, Condensed), usWeightClass and relative style names (e.g. 300, Lt, Light), the Family name.

The CSV file columns are filled reading the font values and pairing them with the strings contained in a configuration file.

The values contained in this file will be written, using FontTools, to the font tables in the second step.

The JSON configuration file.

The 'config.json' file contains the desired style names to pair with each usWidthClass and usWeightClass values of the family, as well as the italic literals:

    "italics": ["It", "Italic"],
    "weights": {
        "250": ["Th", "Thin"],
        "275": ["ExLt", "ExtraLight"],
        "300": ["Lt", "Light"],
        "350": ["Bk", "Book"],
        "400": ["Rg", "Regular"],
        "500": ["Md", "Medium"],
        "600": ["SmBd", "SemiBold"],
        "700": ["Bd", "Bold"],
        "800": ["ExBd", "ExtraBold"],
        "850": ["Hvy", "Heavy"],
        "900": ["Blk", "Black"]
    "widths": {
        "1": ["Cm", "Compressed"],
        "2": ["ExCn", "ExtraCondensed"],
        "3": ["Cn", "Condensed"],
        "4": ["Nr", "Narrow"],
        "5": ["Nor", "Normal"],
        "6": ["Wd", "Wide"],
        "7": ["Extd", "Extended"],
        "8": ["ExExtd", "ExtraExtended"],
        "9": ["Exp", "Expanded"]

Unless you have previously created a configuration file and want to reuse it, you need to create a standard configuration file and eventually customize it.

ftcli wizard init-cfg INPUT_PATH

The above command will create a file named 'config.json' in the INPUT_PATH folder (or parent folder if INPUT_PATH is a file).

Once created the configuration file, you may be in need to edit it according to your needs.

ftcli wizard edit-cfg CONFIG_FILE

Values contained in the configuration file will be used to fill the data.csv file in the next steps.

Let's see an example:

ftcli wizard init-cfg .\IBM-Plex-Sans

Will create a file named config.json in the IBM-Plex-Sans folder.

The json file can be edited manually or with the command line editor:

ftcli wizard edit-cfg .\IBM-Plex-Mono\config.json

This will open the command line editor:


Available command are listed at the bottom:

1: Edit weights
2: Edit widths
3: Edit italics
r: Reset default values
x: exit

For example, let's change the usWeightClass associated to the "Book" style form 350 (the default value) to 450:


In case the selected usWeightClass already is already present, the existing values values are proposed in square brackets, so just press enter if you want to leave something unchanged.

Changes have immediate effect:


The data.csv file

Given a folder containing one or more fonts, we are going to parse all fonts and writing their values into a csv file:

ftcli wizard init-csv .\IBM-Plex-Sans

The above command will do the following:

  • read usWeightClass and usWidthClass values of the fonts and pair them with the corresponding strings contained in the configuration file;
  • check if bold/italic bits are set or cleared;
  • read the family name from nameID 16, or nameID 1 if 16 isn't present;
  • write the found values, together with the file name, in a file named 'data.csv' stored in the working folder.

In case we forgot to create the configuration file, it will be created automatically. We can also use a previously built configuration file using the -c / --config-file switch:

ftcli wizard init-csv .\IBM-Plex-Sans -c .\plex.json

This is the content of the freshly created data.csv file:


usWeightClass values 100 and 200 are not present in our default config.json file, so the integer values have been used as fallback strings. We can handle this editing the csv file:

ftcli wizard edit-csv .\IBM-Plex-Sans


At this point we can edit the configuration file pressing the 'c' key or try to recalculate the usWeight/WidthClass values to align them to the style names present in the configuration file. In this last case, the program will parse a string and, if family name (column J) and width/weight/slope literals present in the configuration file are found, the corresponding usWeight/Width values will be changed, as well as the italic bit.

Press the 'r' key to try to recalculate values, and choose the desired string to parse when asked (the default string is the file name, but can be choosen a different string: 1_1_2 reads nameIDs 1 and 2 from the Macintosh -plartofmID 1- table, 3_4 will read the Windows -platformID 3- full font name -nameID 4-, cff_1 will read the CFF fontName in the CFF table and so on):


And here's the result: usWeightClass values have been set to 250 for the thin styles and to 275 for the ExtraLight ones:


Alternatively, we can can edit the configuration file to set 100 for Thin and 200 for ExtraLight.

Also, the style name associated with 450 is 'Book', while IBM used 'Text'. After editing the json file and recalculating it, this is the final result:


Recalculating the name table.

Now that the csv file contains the desired values, we can write them into the destination fonts using the ftcli wizard recalc-names command.

For example, we want to use Text and Bold instead of Regular and Bold as linked styles (-ls / --linked-styles switch):

ftcli wizard recalc-names .\IBM-Plex-Sans -ls 450 700


In this case there's no need to recalculate the nametable in all fonts. We can always recalculate single fonts:

ftcli wizard recalc-names .\IBM-Plex-Sans\IBMPlexSans-Text.otf -ls 450 700

If the --no-overwrite or the -o / --output-dir switches are not used, existing files will be overwritten.

Use ftcli print names to print on screen the name table:

ftcli print names .\IBM-Plex-Sans\IBMPlexSans-Text.otf


Let's shorten some names:

ftcli wizard recalc-names .\IBM-Plex-Sans\IBMPlexSans-TextItalic.otf -sita 4 -sita 6 -swgt 4 -ls 450 700

The short italics literal ('It') will be written in nameIDs 4 and 6, while the short weight literal ('Tx) will be written in nameID 4 only.

Other options are:

  • -swdt: nameIDs where to use short width literals;
  • -sf / --super-family: to group different width styles (e.g. Normal and Condensed) under the same family;
  • -aui / --alt-uid: by default, namerecord 3 (Unique identifier) is calculated according to the following scheme: 'Version;Vendor code;PostscriptName'. The alternate unique identifier is calculated according to the following scheme: 'Manufacturer: Full Font Name: creation year';
  • -offn, --old-full-font-name: full font name in Microsoft name table is generally a combination of name IDs 1 and 2 or 16 and 17. With this option active, it will be equal to name ID 6 (PostScriptName);
  • -ri, --regular-italic: use '-RegularItalic' instead of '-Italic' in name ID 6.
  • -kr, --keep-regular: use '-RegularItalic' instead of '-Italic' in name ID 6 and 'Regular Italic' instead of 'Italic' in name IDs 2 (Mac only), 4, 17 and 18.
  • -cff: fontNames, FullName, FamilyName and Weight values in the 'CFF' table will be recalculated.
  • -o, --output-dir: specify the output directory where the output files are to be saved. If output_directory doesn't exist, will be created. If not specified, files are saved to the same folder.
  • --recalc-timestamp / --no-recalc-timestamp: keep the original font 'modified' timestamp (head.modified) or set it to current time. By default, original timestamp is kept.
  • --overwrite / --no-overwrite: overwrite existing output files or save them to a new file (numbers are appended at the end of file name). By default, files are overwritten. By default, files are overwritten.