glyphs-cli 0.4.0

Command-line tool for the Glyphs font editor

glyphs – Glyphs command-line tool

The glyphs command-line tool is a companion to the Glyphs font editor. This CLI tool is targeted at scripting and automation of font export and editing.

Installation

Install the Glyphs CLI with pip:

pip install glyphs-cli

The command above installs the glyphs tool. This command-line tool itself does not know how to export fonts. Instead, it uses the Glyphs app installed on your Mac. See the section “Selecting an app version” for details.

Subcommands

The glyphs command is divided into subcommands:

• glyphs export – exporting font files
• glyphs run – running a Python script using the Glyphs API
• glyphs version – managing Glyphs installations

Learn all details about a subcommand by running it with the --help flag (for example, glyphs export --help).

glyphs export [<source> ...] – Exporting font files

This command-line tool itself does not know how to export fonts. Instead, it uses the Glyphs app installed on your Mac. That way, the results are the same whether exporting from the Glyphs app or from the command-line tool.

# export using the latest installed Glyphs version
glyphs export SomeFont.glyphs

(The Glyphs app does not need to be running and is not launched when using this command.)

You can export multiple source files:

glyphs export SomeFont.glyphs OtherFont.glyphspackage

By default, all instances of the files are exported, including variable fonts.

Outline format and file container

Use the --format argument to select the outline formats. Supported values are cff for PostScript/CFF and tt for TrueType. Multiple formats can be combined using commas: cff,tt. cff is that default for static fonts, tt for variable fonts.

glyphs export --format tt SomeFont.glyphspackage

Use the --container argument to select the file containers. Supported values are standard for OTF/TTF files and woff/woff2 for WOFF/WOFF 2 files. Multiple containers can be combined using commas: standard,woff2. standard is the default.

glyphs export --container woff2 SomeFont.glyphspackage

Output directory

Use the --output/-o option to specify the output directory for the exported font files. If unset, fonts are exported to the current working directory.

glyphs export --output ~/Desktop/ SomeFont.glyphspackage

Export configuration

Use glyphs export --config <file> to provide a configuration file that can change export settings and specify specific instances.

The file format is JSON5, a superset of JSON with support for comments, unquoted keys, and trailing commas.

Schema of configuration file format

The file is an object with the following values:

• "settings": (optional) Export settings.
• "sourceFiles": (optional) List of file paths to source files to export. These source files are used in addition to the files specified as <source> arguments.

Each source file in "sourceFiles" is an object with the following values:

• "filePath": File path to the source file.
• "instances": (optional) Array of instance configurations. If unset, uses all instances of the source file.
• "settings": (optional) Export settings overriding the config-file-level settings.

Each instance configuration in "instances" is an object with the following values:

• "selector": Selects an instance from the source file.
• "fileName": (optional) Specifies a custom file name for the exported font file.
• "settings": (optional) Export settings overriding the source-file-level settings.

Each instance selector is an object with the following values:

• "index": (optional) Zero-based index of the instance in the list of instances.
• "name": (optional) Name of the instance.
• "familyName": (optional) Family name in the default language.
• "type": (optional) One of "single" or "variable".
• "predicate": (optional) NSPredicate expression matching an instance.

An instance selector matches instances for which all specified values are equal. Additionally, an instance selector can be an integer (equivalent to {index: #}) or a string (equivalent to {name: #}).

Export settings can be specified via command-line arguments (for example, --output, --format, …), at the config-file level, per source file, and per instance. Settings are inherited such that more specific scopes override less specific scopes. For example, an outline format specified for an instance overrides values specified for the source file, config file, or command-line arguments. The settings offer the following optional values:

• "outputPath": File path to the directory into which to export the font files.
• "outlineFormats": Array of strings; "cff" (CFF/PostScript) or "tt" (TrueType).
• "containerFormats": Array of strings; "standard" (OTF/TTF), "woff" (WOFF), or "woff2" (WOFF 2).
• "autohint", "removeOverlap", "useSubroutines", "useProductionNames", "optimizeDeltas": Explicitly enabled or disabled these options. If unset, the default choice of the selected Glyphs app version is used.

Example configuration files

For example, the following config file defines that both CFF and TrueType versions of all instances should be exported:

{
  settings: {
    outlineFormats: ["cff", "tt"],
  },
}

The config above is equivalent to passing the --format cff,tt argument.

Settings can also be scoped to source files:

{
  settings: {
    outlineFormats: ["cff", "tt"],
  },
  sourceFiles: [
    {
      filePath: "SomeFont.glyphspackage",
    },
    {
      filePath: "OtherFont.glyphspackage",
      settings: {
        outlineFormats: ["tt"],
      },
    },
  ],
}

In this example, SomeFont.glyphspackage and any other source files provided as <source> arguments are exported using both CFF and TrueType outlines, but OtherFont.glyphspackage is exported using only TrueType outlines.

Settings can also be specifically scoped to instances:

{
  sourceFiles: [
    {
      filePath: "SomeFont.glyphspackage",
      instances: [
        {
          selector: {name: "Regular"},
        },
        {
          selector: {name: "Regular"},
          fileName: "SomeFont-Regular-SourceGlyphNames",
          settings: {
            useProductionNames: false,
          },
        },
      ],
    },
  ],
}

In this example, the same instance is exported twice, each time with different settings. A separate fileName is specified for the second instance so the two instances don’t use the same export file name and thus don’t overwrite each other.

JSON export report

Use glyphs export --json to write a JSON report for each processed instance on a separate line.

Schema of JSON report

Each report is an object with the following values:

• "sourceFilePath": Absolute file path to the source file.
• "instanceName": Name of the instance.
• "exportConfiguration": Configuration used for the export.
• "exportFilePath": Absolute file path to the exported font file. May be null.
• "warnings", "errors": Array of objects with string values for the keys title, instancePath, and description.

"exportConfiguration" is an object with the following values:

• "outlineFormat": "cff" (CFF/PostScript) or "tt" (TrueType).
• "containerFormat": "standard" (OTF/TTF), "woff" (WOFF), or "woff2" (WOFF 2).
• "autohint", "removeOverlap", "useSubroutines", "useProductionNames", "optimizeDeltas": (optional, Boolean) Whether these options were explicitly enabled or disabled. If unset, the default behavior of the selected Glyphs app version was used.

Other glyphs export options

• --app/-a selects the Glyphs version to use for export. See “Selecting an app version” for details.
• --script/-s runs a Python script before the font files are exported. See “Python scripting” for details.
• --plugins allows to control which plug-ins are loaded. See “Selecting plug-ins to load” for details.
• --python allows choosing a specific Python version. See “Selecting a Python version” for details.
• --quiet/-q suppresses logging to stderr.

glyphs run [<script>] – Running a Python script

The glyphs run command runs a Python script with access to the Glyphs API.

glyphs run SomeScript.py

If no script file is provided, an interactive Python shell (REPL) is launched:

glyphs run
>>> font = Glyphs.open("SomeFont.glyphs")
>>> font.glyphs["A"]
<GSGlyph 0x987654321> A

See “Python scripting” for details.

Loading source files

The --input/-i argument loads source files to use used from the script.

glyphs run SomeScript.py --input SomeFont.glyphs

The input argument accepts multiple values up to the next option argument:

glyphs run SomeScript.py -i SomeFont.glyphs OtherFont.glyphs

Other glyphs run options

• --app/-a selects the Glyphs version to use for editing. See “Selecting an app version” for details.
• --plugins allows to control which plug-ins are loaded. See “Selecting plug-ins to load” for details.
• --python allows choosing a specific Python version. See “Selecting a Python version” for details.
• --quiet/-q suppresses logging to stderr.

glyphs version – Managing app versions

The glyphs tool uses Glyphs installations for working with Glyphs source files. Such an installation can be a Glyphs app that is installed on the Mac or a version of Glyphs that was specifically downloaded and installed using the glyphs version command.

glyphs version list [<selector> ...]

Run glyphs version list to see which Glyphs versions are available to the glyphs tool. The output is a table with three columns:

• display: the display version, for example, 3.4 or 3.2.5
• build: the build number, for example, 3517 or 3124
• location: the file path of the installation

Multiple versions can have the same display version, but the build number is unique to each version of Glyphs. The location is either a file path to the installation, or the keyword <installed> for installations that are managed by the glyphs tool.

You can filter for a subset of versions by providing a list of version selectors as arguments:

# list only versions matching 3.3 or 3.4
glyphs version list 3.3 3.4

A selector such as 3 matches any 3.# version, 3.4 matches any 3.4.# version, and so on. You can also use build numbers as selectors.

Listing versions available for download

Pass the --remote flag to also list all versions available to download and install. These versions can be installed using glyphs version install <version>. Remote versions show the keyword <remote> for their location.

glyphs version list --remote

Machine-readable version listing

Pass the --plain flag to output a tab-separated values (TSV) version of the table. Other informative text is omitted so the table can be processed by other tools.

glyphs version list --plain

Installing Glyphs versions

Run glyphs version install <version> to install that version. <version> can be a display version like 3.4 or a build number like 3124. When specifying a display version, the latest stable version is installed unless --beta is set.

Versions installed using this command are managed by the glyphs tool. Use glyphs version uninstall <version> to delete a managed version.

When installing, pass the --app flag to install the version as a full Glyphs app into the system’s Applications directory instead of installing it as a managed version.

Choose a custom installation location using the --output/-o option. In case an installation already exists, use --overwrite to replace it with the newly downloaded version.

Selecting an app version

The glyphs export and glyphs run commands allow choosing a specific Glyphs app version using the --app/-a option:

# export using latest Glyphs 3 version that is installed on the Mac
glyphs export --app 3 SomeFont.glyphs

Further, the tool can select any other Glyphs version. If you have multiple Glyphs app versions installed, you can choose among them:

# export using a specific version
glyphs export --app 3.4 SomeFont.glyphs
# export using a specific build number
glyphs export --app 3432 SomeFont.glyphs
# export using a specific app
glyphs export --app '/Applications/Glyphs 3.app' SomeFont.glyphs

This allows you to edit files with one Glyphs version and use the tool to export the files using another Glyphs version. That can be useful in a team where different people might use different Glyphs app versions but you still want everyone to export using the exact same version.

If no --app option is given, the tool uses the latest Glyphs installation.

Use --app source to select the Glyphs version with which the source files were last saved:

glyphs export --app source SomeFont.glyphs

This causes an error if that specific Glyphs version is not installed. In that case, consider installing the version with glyphs version install <version> or selecting a Glyphs version that is installed using the --app option. --app source cannot be used when the source files specify different app versions or when no source files are provided.

Python scripting

Python scripting is possible in the glyphs run command as well as in the glyphs export command with the --script/-s option.

The scripting environment has full access to the Glyphs Python API. The source files that were specified as command-line arguments are accessible via Glyphs.fonts. If there is only one source file, you can access it directly as Font and Glyphs.font. Open additional source files using Glyphs.open(filePath).

Modifications that are made to the GSFont are not automatically saved back to the source file. Instead, call someFont.save() to save the changes.

Printing using Python’s print() is written to stdout.

Selecting plug-ins to load

The glyphs export and glyphs run commands have a --plugins option with which you can select the plug-ins to load. The option takes a comma-separated set of selectors. Each selector is one of the following forms:

• A name selects that plug-in from the app’s plug-ins (for example, SomePlugin or SomePlugin.glyphsPlugin).
• A file path selects the plug-in at the given location (for example, ./SomePlugin.glyphsPlugin).
• The keyword 'app' selects all plug-ins installed for the selected app version.

For example:

• --plugins OptimizeStartNodes,Beowulferize loads the two plug-ins with the given names and no other plug-ins.
• --plugins app,tools/MyFilter.glyphsFilter loads all of the plug-ins installed for the selected app version and an additional plug-in which is located at tools/MyFilter.glyphsFilter.
• --plugins '' loads no plug-ins.

The default value of the option is app.

Selecting a Python version

The glyphs export and glyphs run commands have a --python option for selecting a specific Python version. By default, the CLI tool will use the same Python version that is also configured for the selected app. You can choose a different Python version using the --python option:

glyphs export --python .../Python.framework/Versions/3.14/Python ...