Metadata-Version: 2.1
Name: glyphs-cli
Version: 0.4.1
Summary: Command-line tool for the Glyphs font editor
Author-email: Florian Pircher <fp@glyphsapp.com>
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Other
Classifier: Topic :: Text Processing :: Fonts
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# `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`:

```sh
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](#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.

```sh
# 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:

```sh
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.

```sh
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.

```sh
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.

```sh
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](https://json5.org), a superset of JSON with support for comments, unquoted keys, and trailing commas.

<details>
<summary>Schema of configuration file format</summary>

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.
</details>

<details>
<summary>Example configuration files</summary>

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

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

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

Settings can also be scoped to source files:

```js
{
  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:

```js
{
  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.
</details>

#### JSON export report

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

<details>
<summary>Schema of JSON report</summary>

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.
</details>

#### Other `glyphs export` options

- `--app`/`-a` selects the Glyphs version to use for export. See “[Selecting an app version](#selecting-an-app-version)” for details.
- `--script`/`-s` runs a Python script before the font files are exported. See “[Python scripting](#python-scripting)” for details.
- `--plugins` allows to control which plug-ins are loaded. See “[Selecting plug-ins to load](#selecting-plug-ins-to-load)” for details.
- `--python` allows choosing a specific Python version. See “[Selecting a Python version](#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.

```sh
glyphs run SomeScript.py
```

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

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

See “[Python scripting](#python-scripting)” for details.

#### Loading source files

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

```sh
glyphs run SomeScript.py --input SomeFont.glyphs
```

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

```sh
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](#selecting-an-app-version)” for details.
- `--plugins` allows to control which plug-ins are loaded. See “[Selecting plug-ins to load](#selecting-plug-ins-to-load)” for details.
- `--python` allows choosing a specific Python version. See “[Selecting a Python version](#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:

```sh
# 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.

```sh
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.

```sh
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:

```sh
# 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:

```sh
# 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:

```sh
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](https://docu.glyphsapp.com).
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:

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