Skip to content

Command reference

Every command, with the help text generated from the binary itself. gotpm help <command> prints the same thing in your terminal.

-v/--verbose is accepted everywhere and is repeatable: -vv is louder than -v.

Project commands and standalone commands

The commands fall into two groups, and the difference decides which flags they take.

Project commands — add, sync, remove, font add and font remove — take the current project as their subject. They read typst.toml and gotpm.lock, and install or delete the whole dependency graph those two describe. Run one outside a project and it says so. bump and locate read the project as well, but change no dependency.

Standalone commands — install, uninstall, list, check, publish, init, update, cache, config, self, font install, font uninstall and font search — need no project. install and uninstall act on a single package version, which is why they are the only two that accept --install-dir: that flag names a directory to receive one package's files directly, and a dependency graph does not fit in one. A project command always works on the package directory.

Environment variables

Variable Effect
$TYPST_PACKAGE_PATH Moves the package directory itself, layout and all. Honoured by every command.
$GOTPM_INSTALL_DIR The ambient form of --install-dir: a single-package destination, set once instead of typed each time. Ignored by every command that does not offer the flag.
$GITHUB_TOKEN Sent to the GitHub API, and only there, when the font commands look up a commit or the family list. Lifts the limit of 60 unauthenticated requests an hour.

gotpm reads no font path of its own. Typst finds the fonts gotpm installs only when $TYPST_FONT_PATHS points at the font directory — see font.

$GOTPM_INSTALL_DIR is not a setting for where gotpm keeps its data. Left set in a shell, it sends the next gotpm install into a flat directory Typst cannot import from, while add, sync and remove carry on using the package directory — which is why locate reports it as a warning rather than a fact.

add

Add a repository as a dependency of the current project.

The package is installed under the @gotpm namespace, together with
everything it depends on, and recorded in two files next to typst.toml:

  typst.toml   gains the import under [tool.gotpm].dependencies
  gotpm.lock   pins every package to the exact commit it was fetched from

Commit both. gotpm.lock is what lets anyone who checks the project out run
'gotpm sync' and get the same packages, and it is the only place recording
where a dependency's own dependencies come from.

Without --rev the newest release tag is used, or the current HEAD when the
repository has no release tags.

A package that does not sit at the root of its repository is named by its
package path, separated from the repository by '//'.

USAGE

  gotpm add <repository> [--flags]

EXAMPLES

  gotpm add github.com/user/repo
  gotpm add github.com/user/repo -t v0.1.2
  gotpm add git@github.com:user/repo.git
  gotpm add github.com/user/monorepo//packages/common

FLAGS

  -f --force    Replace a package installed from a different repository.
  -h --help     Help for add
  -t --rev      The revision (hash or tag) to pin. Defaults to the newest release.
  -v --verbose  Enable verbose output

The package directory is shared by every project on your machine. If @gotpm/cetz:0.3.1 is already installed from a different repository, add refuses rather than overwrite it, since that would change what your other projects import. --force overrides that, deliberately.

The fonts a dependency declares come along: add reads their pins from the dependency's own gotpm.lock, records them in yours and installs them into the font directory. They are pinned, not declared — typst.toml gains no font. Where your lock already pins the family at another commit, that pin is kept and the conflict is reported.

Managing dependencies

bump

Change the version of the current package, or print it.

Use this command to change the version of the Package or to display it.
Valid arguments can be:
    - major
    - minor
    - patch
    - a valid semantic version (e.g. 0.1.2)

USAGE

  gotpm bump [increment|version] [--flags]

EXAMPLES

  # bump with a given increment
  gotpm bump major

  # set to a specific version
  gotpm bump 0.1.2

FLAGS

  --dry-run          Perform a dry-run
  -h --help          Help for bump
  -c --show-current  Show the version of the current package
  -n --show-next     Show the version of the package if it where bumped
  -v --verbose       Enable verbose output

cache

Manage the repositories gotpm has cloned and the Universe index it has fetched.

Manage the cache of gotpm

USAGE

  gotpm cache [command] [--flags]

COMMANDS

  clear [--flags]  Clear the Cache

FLAGS

  -h --help        Help for cache
  -v --verbose     Enable verbose output

The cache exists only to avoid repeating work. Deleting it loses nothing; the package directory is never cache.

The fork clones publish stages submissions in are not cache either, and a plain gotpm cache clear leaves them alone. gotpm cache clear --forks removes them instead — and with them any gotpm publish --local commit not pushed yet. A fork.path you configured is never touched.

The font directory is not cache either. gotpm cache clear --fonts removes every installed font family; gotpm sync brings back the ones a project pins. A plain clear only drops the cached list font search reads.

check

Report whether every package a Typst file imports will resolve when it is compiled.

Check if all dependencies, that are imported by a file are available on the system

USAGE

  gotpm check <file> [--flags]

FLAGS

  -h --help     Help for check
  -v --verbose  Enable verbose output

A package outside the Typst Universe has to be present in the package directory; a Universe package need only exist in the index, because the compiler downloads it and gotpm does not interfere.

config

Read and write gotpm's own configuration, stored as TOML in the user config directory.

Manage gotpm configuration values, stored as TOML in the user config directory.

Available keys:
    - fork.path  local directory a forked package repository gets cloned into
    - fork.url   URL of the forked package repository

set and unset rewrite the whole file, so comments added with edit are lost.

USAGE

  gotpm config [command] [--flags]

COMMANDS

  edit               Open the config file in your editor
  get <key>          Print the value of a config key
  list               List all config keys and their values
  set <key> <value>  Set the value of a config key
  unset <key>        Clear the value of a config key

FLAGS

  -h --help          Help for config
  -v --verbose       Enable verbose output

Both keys concern publishing: fork.url is required before gotpm publish will run, and fork.path defaults to a location derived from fork.url — forks/<host>/<owner>/<repo> inside gotpm's data directory — so each fork gets a clone of its own.

font

Install font families from Google Fonts, and pin the ones a project needs.

Download and install fonts, and make typst projects reproducible.

Fonts come from the Google Fonts repository (github.com/google/fonts) and are
kept in gotpm's font directory, one directory per family. Typst does not look
there on its own; point $TYPST_FONT_PATHS at it, e.g. in ~/.bashrc:

  export TYPST_FONT_PATHS="$(gotpm locate fonts)"

Names are matched the way the repository lays out its directories, ignoring
case, spaces and punctuation, so "Open Sans" and "opensans" are the same font.
Quote names that contain spaces.

USAGE

  gotpm font [command] [--flags]

COMMANDS

  add <name> [--flags]        Add a font family to this project.
  install <name> [--flags]    Install a font family into the font directory.
  remove <name>               Remove a font family from this project.
  search [query] [--flags]    Search the font families Google Fonts offers.
  uninstall <name> [--flags]  Delete a font family from the font directory.

FLAGS

  -h --help                   Help for font
  -v --verbose                Enable verbose output

Fonts are kept in gotpm's font directory, one directory per family. Typst does not look there on its own, so point $TYPST_FONT_PATHS at it once, e.g. in ~/.bashrc:

export TYPST_FONT_PATHS="$(gotpm locate fonts)"
Command Kind Does
font install <name> standalone Installs the newest commit of a family
font uninstall <name> standalone Deletes an installed family
font search [query] standalone Lists the families whose name contains the query
font add <name> project Installs a family, pins it in gotpm.lock and declares it in typst.toml
font remove <name> project Drops a family from typst.toml and gotpm.lock; the files stay

A declared font is written under [tool.gotpm], by the name Typst's font setting uses:

[tool.gotpm]
fonts = [
  "Open Sans",
]

Its pin in gotpm.lock names the commit of the Google Fonts repository and the SHA-256 of every file, so gotpm sync installs exactly the files that were added, wherever it runs. A lock holding font pins is format version 2, which gotpm older than font support refuses to read (ADR 0007); a lock without them stays version 1.

Names match the way the repository lays out its directories, ignoring case, spaces and punctuation: "Open Sans", "open sans" and opensans are one family.

The font directory is shared by every project on your machine, and holds one copy of each family. Two projects pinning different commits of a family cannot both be satisfied: the last sync wins and says what it replaced. A family directory gotpm did not create — one without a .gotpm.json — is never replaced or deleted without --force; sync skips it with a warning.

Variable fonts

The Google Fonts repository ships most families as variable fonts only, such as Roboto[wdth,wght].ttf. Typst renders a variable font at its default instance, so bold and light text come out regular. gotpm warns when a family has no static files.

init

Scaffold a minimal Typst package: a typst.toml and a lib.typ.

Initialize a new minimal Typst Package

USAGE

  gotpm init [name] [--flags]

EXAMPLES

  # initialize a new Package
  gotpm init

  # scaffold into a new directory
  gotpm init mypkg

FLAGS

  -h --help     Help for init
  -v --verbose  Enable verbose output

install

Install a package into the package directory, so the Typst compiler can find it.

All files that are not specifically excluded get copied into the package
directory, $DATA_DIR/typst/packages, where the $DATA_DIR is dependent on the
machine's operating system, under namespace/name/version. Set
$TYPST_PACKAGE_PATH to put that package directory somewhere else: the layout
inside it is unchanged, and typst imports from it the same way.

--install-dir, and the GOTPM_INSTALL_DIR environment variable behind it, are a
different thing. The directory named there receives the package's files
directly, with no namespace/name/version layout around them, which is not a
directory typst imports from and not one gotpm scans. It is an output
destination — vendoring one package into a build directory, or looking at what
an install would produce. The flag takes precedence over the environment
variable. Neither reaches 'add', 'sync' or 'remove': those work on a dependency
graph, which does not fit in a directory holding one package. -r/--remote
installs a graph too, once the repository has dependencies of its own, so
--install-dir is refused there unless it turns out to be single-package.

-r/--remote fetches a repository instead of using the working tree, and
installs everything it depends on alongside it, the same way 'add' does — a
dependency with no gotpm.lock at all is skipped with a warning, but one whose
lock is simply missing an entry still fails the install. Without -t/--rev the
newest release tag is used, or the current HEAD when the repository has none;
pass -t HEAD explicitly to keep pinning HEAD regardless of releases. A package
that does not sit at the root of its repository is named by its package path,
separated from the repository by '//'.

USAGE

  gotpm install [path] [--flags]

EXAMPLES

  gotpm install
  gotpm install . -e
  gotpm install -n preview
  gotpm install -r github.com/user/repo -t v0.1.2
  gotpm install -r github.com/user/repo -t HEAD
  gotpm install -r github.com/user/monorepo//packages/common
  gotpm install path/to/package -n preview

FLAGS

  -e --editable   Create a symlink to the source directory instead of copying files.
  -f --force      Overwrite an already-installed package.
  -h --help       Help for install
  --install-dir   A directory holding one package's files, without namespace/name/version layout (env: $GOTPM_INSTALL_DIR)
  -n --namespace  The namespace in which the package should be available. (local)
  -r --remote     The remote repository which should be installed.
  -t --rev        The revision (hash or tag) to check out. Defaults to the newest release.
  -v --verbose    Enable verbose output

Authoring a package

list

List every package installed on this machine.

List all locally installed Packages

USAGE

  gotpm list [--flags]

EXAMPLES

  # list all available Packages
  gotpm list

FLAGS

  -h --help     Help for list
  -v --verbose  Enable verbose output

locate

Show every path and directory gotpm reads or writes.

Show the paths and directories gotpm reads and writes.

Without a key, every path is listed, grouped by what it belongs to. The
project group is only shown when the working directory belongs to a typst
project.

With a key, only that path is printed, unstyled and on its own, so it can be
used directly in a shell.

The packages path answers to $GOTPM_INSTALL_DIR first and $TYPST_PACKAGE_PATH
second, and the note beside it says which one applied. They are not the same
kind of path: $TYPST_PACKAGE_PATH moves the package directory typst imports
from, keeping its namespace/name/version layout, while $GOTPM_INSTALL_DIR names
a directory that receives one package's files directly, without that layout.

Nothing is created: a path that does not exist yet is still where gotpm would
look for it.

USAGE

  gotpm locate [key] [--flags]

EXAMPLES

  # Show every path
  gotpm locate

  # Print one path, for use in a shell
  cd "$(gotpm locate packages)"

  # Let typst find the fonts gotpm installs, e.g. in ~/.bashrc
  export TYPST_FONT_PATHS="$(gotpm locate fonts)"

FLAGS

  -h --help     Help for locate
  -v --verbose  Enable verbose output

Keys

Key Points at
packages The Typst package directory packages are installed into
data-dir gotpm's own data directory
config-dir gotpm's own config directory
config config.toml, gotpm's configuration file
index index-cache.json, the cached package index
remotes The cache of cloned remote repositories
fonts The fonts installed by gotpm font install, one directory per family
root The directory of the current project
manifest The project's typst.toml
lock The project's gotpm.lock

root, manifest and lock describe the project the working directory belongs to. Without one, they are left out of the listing, and asking for them by name is an error.

The packages path follows the same overrides gotpm install does — $GOTPM_INSTALL_DIR first, then $TYPST_PACKAGE_PATH — and the listing notes which one applied:

$ GOTPM_INSTALL_DIR=/tmp/scratch gotpm locate
Typst
  packages   /tmp/scratch (via $GOTPM_INSTALL_DIR)
...

Typst does not look in the fonts directory on its own. Point $TYPST_FONT_PATHS at it, for example in ~/.bashrc, and every installed font is available to typst compile:

export TYPST_FONT_PATHS="$(gotpm locate fonts)"

publish

Stage a package version in a fork of the Typst Universe repository, ready for a pull request.

Publish a Typst Package to the Typst Universe.
This involves pushing your changes to a fork of the github.com/typst/packages repo
on a dedicated branch, ready for you to open a Pull Request from.

GoTPM will know where your fork lives on disc, and handle committing your
Package files to the correct location.

USAGE

  gotpm publish [--flags]

EXAMPLES

  gotpm publish
  gotpm publish --local
  gotpm publish --no-hooks

FLAGS

  -h --help     Help for publish
  --local       Stop after committing to the local fork clone; do not push.
  -m --message  Custom commit message
  --no-hooks    Skip the package's pre- and post-publish hooks.
  -v --verbose  Enable verbose output

Publishing

remove

Remove a dependency from the current project.

Takes the import string exactly as it appears in typst.toml, so the
version being removed is never in doubt.

The dependency is dropped from typst.toml and from gotpm.lock, along with
any package only it pulled in. The installed files are left in the package
directory, because other projects on this machine may import the same version;
--prune deletes them too.

USAGE

  gotpm remove <@namespace/name:version> [--flags]

EXAMPLES

  gotpm remove @gotpm/cetz:0.3.1
  gotpm rm @gotpm/cetz:0.3.1 --prune

FLAGS

  -h --help     Help for remove
  --prune       Delete the removed packages from the package directory as well.
  -v --verbose  Enable verbose output

Removing a dependency also drops the transitive ones nothing else needs any more. A package another dependency still requires stays:

$ gotpm remove @gotpm/cetz:0.3.1
info: removed @gotpm/cetz:0.3.1
info:   no longer needed: @gotpm/oxifmt:0.2.1
info: the package files are still in the package directory; pass --prune to delete them

self

Inspect or update the gotpm binary itself.

Inspect or manage the gotpm binary

USAGE

  gotpm self [command] [--flags]

COMMANDS

  update [--flags]  Update gotpm to the latest version from GitHub Releases
  version           Print build information for the gotpm binary

FLAGS

  -h --help         Help for self
  -v --verbose      Enable verbose output

gotpm self update replaces the running binary with the latest GitHub release. Installs made through a package manager are better updated through it instead.

sync

Install everything the current project depends on. This is what a fresh checkout needs before it compiles.

Reads typst.toml and gotpm.lock and makes the package directory match them.
This is what a fresh checkout needs before it compiles.

Every package is installed at the commit gotpm.lock pins, not at whatever
its tag points at today. The fonts the project and its dependencies declare
are installed into the font directory the same way, at their pinned commits. Lock entries that nothing in typst.toml
requires
any more are dropped.

--frozen fails instead of rewriting gotpm.lock, which is what a CI job
wants: a lock that disagrees with typst.toml is a change somebody forgot
to commit.

USAGE

  gotpm sync [--flags]

EXAMPLES

  gotpm sync
  gotpm sync --frozen

FLAGS

  -f --force    Replace a package from a different repository or a font family gotpm did not install.
  --frozen      Fail instead of updating gotpm.lock.
  -h --help     Help for sync
  -v --verbose  Enable verbose output

A dependency added to typst.toml by hand cannot be synced: an import statement names a package, never the repository it comes from, so only you know where it should be fetched from. Use gotpm add <repository> instead. A font added to typst.toml by hand is refused the same way; use gotpm font add <name>.

The fonts the lock pins — declared by the project or by its dependencies — are installed into the font directory at their pinned commits, each file checked against its recorded digest.

$ gotpm sync
ERROR

  Declared dependency is missing from the lock: @gotpm/cetz:0.3.1
  note: gotpm.lock records where a package comes from; run 'gotpm add <url>' to add it properly.

uninstall

Delete an installed package from the package directory — one version, every version of a package, or a whole namespace.

Removes a locally installed Typst package from the package directory.

Naming a namespace and nothing else removes the whole namespace, after asking
for confirmation. Adding a package, a version or --all narrows the removal back
to a package inside that namespace.

Which package directory is read follows $TYPST_PACKAGE_PATH, keeping the
namespace/name/version layout inside it.

--install-dir, and the GOTPM_INSTALL_DIR environment variable behind it, point
somewhere else entirely: at a directory holding one package's files directly,
without that layout. The flag takes precedence over the environment variable.
A namespace cannot be removed from such a directory, since there is no
namespace layout in it to remove.

USAGE

  gotpm uninstall [name] [--flags]

EXAMPLES

  # get package metadata from typst.toml
  gotpm uninstall
  gotpm uninstall foo

  # uninstall specific package from 'local' or 'preview'
  gotpm uninstall foo -V 0.1.2
  gotpm uninstall foo -V 0.1.2 -n preview

  # all versions of foo in namespace 'local' or 'preview'
  gotpm uninstall foo --all
  gotpm uninstall foo -n preview --all

  # the whole 'preview' namespace, with and without the prompt
  gotpm uninstall -n preview
  gotpm uninstall -n preview --yes

FLAGS

  --all           Uninstall all Packages from a given namespace or all versions of a package.
  --dry-run       Perform a dry run.
  -h --help       Help for uninstall
  --install-dir   A directory holding one package's files, without namespace/name/version layout (env: $GOTPM_INSTALL_DIR)
  -n --namespace  The namespace from which the package should be removed from. On its own, removes the whole namespace. (local)
  -v --verbose    Enable verbose output
  -V --version    The specific version of a package that should be removed.
  -y --yes        Skip the confirmation prompt when removing a namespace.

Removing a namespace asks before it deletes anything, and refuses outright when there is no terminal to answer:

$ gotpm uninstall -n preview
warning: will delete @preview: 2 packages, 3 versions
delete the whole namespace? [y/N]

$ gotpm uninstall -n preview --dry-run
warning: dryrun would delete "~/.local/share/typst/packages/preview": 2 packages, 3 versions

update

Rewrite the @preview imports of a source file to the latest published version of each package.

Update all dependencies from a file or directory to their latest version.

USAGE

  gotpm update [path...] [--flags]

EXAMPLES

  # update import statements in a file (writes back in place)
  gotpm update foo.typ

  # update all .typ files in a directory (writes back in place)
  gotpm update src/

  # recursively update all .typ files in a directory
  gotpm update src/ -r

  # update files with custom extensions
  gotpm update src/ --ext .typ --ext .md

  # pipe content via stdin, write result to stdout
  cat foo.typ | gotpm update

  # pipe content via stdin, write result to a file
  cat foo.typ | gotpm update -o foo.typ

  # read from a file, write result to a different file
  gotpm update foo.typ -o bar.typ

FLAGS

  --ext           File extensions to process when input is a directory ([.typ])
  -h --help       Help for update
  --no-cache      Skip reading and writing the package index cache
  -o --output     Output file (defaults to input file, or stdout when reading from stdin)
  -r --recursive  Process recursively (only applies when input is a directory)
  -v --verbose    Enable verbose output

It works on imported packages, not on declared dependencies, and touches no lock. The Universe index is fetched once and every import resolved against it, so the cost is one network request regardless of how many imports a file has.