Made with ❤️ by

Typst CLI Documentation

A Quick Reference to the Typst CLI tool

Not officially affiliated with Typst

Overview

Typst CLI is the command-line interface for the Typst typesetting system. It provides tools for compiling documents, watching for changes, managing fonts and packages, and querying document content.

Installation & Build Information

Version Information

  • Version can be checked with environment variable TYPST_VERSION
  • Build commit SHA available via TYPST_COMMIT_SHA
  • Supports multiple platforms: Linux, macOS, Windows (x86_64, aarch64, ARM)

Build Features

  • embed-fonts: Embeds default fonts into the binary
  • http-server: Enables built-in HTTP server for watch mode and HTML export
  • self-update: Allows CLI to update itself
  • vendor-openssl: Vendors OpenSSL (Linux only)

Commands

1. typst compile (alias: c)

Compiles a Typst document into a supported output format.

Usage:

typst compile [OPTIONS] <INPUT> [OUTPUT]

Arguments:

  • <INPUT>: Path to input Typst file (use - for stdin)
  • [OUTPUT]: Path to output file (PDF, PNG, SVG, or HTML)

Options:

Output Format

  • --format, -f <FORMAT>: Output format (pdf, png, svg, html)
  • --pages <PAGES>: Specific pages to export (comma-separated)
    • Examples: 2,5 (pages 2 and 5), 3-6 (pages 3-6), 8- (page 8 onwards)
    • Uses {p} for page numbers, {0p} for zero-padded, {t} for total pages

PDF Options

  • --pdf-standard <STANDARD>: PDF standards (comma-separated)
    • Standards: 1.4, 1.5, 1.6, 1.7, 2.0
    • PDF/A: a-1b, a-1a, a-2b, a-2u, a-2a, a-3b, a-3u, a-3a, a-4, a-4f, a-4e
    • PDF/UA: ua-1
  • --no-pdf-tags: Disable PDF accessibility tags

Image Export

  • --ppi <PPI>: Pixels per inch for PNG export (default: 144.0)

Dependencies

  • --deps <PATH>: Write compilation dependencies to file
  • --deps-format <FORMAT>: Dependency file format (json, zero, make)
  • --make-deps <PATH>: (Deprecated) Write Makefile dependencies

Processing

  • --jobs, -j <JOBS>: Number of parallel jobs (defaults to CPU count)
  • --diagnostic-format <FORMAT>: Diagnostic output format (human, short)

Post-Compilation

  • --open [VIEWER]: Open output with default viewer or specified program
  • --timings [OUTPUT_JSON]: Generate performance timing data (experimental)

2. typst watch (alias: w)

Watches an input file and recompiles on changes.

Usage:

typst watch [OPTIONS] <INPUT> [OUTPUT]

Options:

  • All compile options are supported
  • Additional HTTP server options (if http-server feature enabled):
    • --no-serve: Disable built-in HTTP server for HTML export
    • --no-reload: Disable live reload script injection
    • --port <PORT>: Specify server port (default: first free port in 3000-3005)

Behavior:

  • Clears terminal on each compilation
  • Shows timestamp and compilation status
  • Displays compilation duration
  • Caches exported images to avoid re-exporting unchanged pages

3. typst init

Initializes a new project from a template.

Usage:

typst init <TEMPLATE> [DIR]

Arguments:

  • <TEMPLATE>: Template to use (e.g., @preview/charged-ieee)
    • Supports version specification: @preview/template:0.1.0
    • Defaults to latest version if not specified
  • [DIR]: Project directory (defaults to template name)

Features:

  • Downloads template from package registry if needed
  • Validates template manifest
  • Creates project directory with template contents
  • Provides instructions for getting started

4. typst query

Extracts metadata from a compiled document using selectors.

Usage:

typst query [OPTIONS] <INPUT> <SELECTOR>

Arguments:

  • <INPUT>: Path to input Typst file (use - for stdin)
  • <SELECTOR>: Typst selector to query elements

Options:

  • --field <FIELD>: Extract specific field from elements
  • --one: Expect and retrieve exactly one element
  • --format <FORMAT>: Serialization format (json, yaml)
  • --pretty: Pretty-print JSON output
  • --target <TARGET>: Compilation target (paged, html)

Examples:

# Query all headings
typst query main.typ heading

# Get value of a specific field
typst query main.typ heading --field body

# Get exactly one element
typst query main.typ selector --one

5. typst fonts

Lists all discovered fonts in system and custom font paths.

Usage:

typst fonts [OPTIONS]

Options:

  • --variants: List style variants of each font family

Output: Shows font families and optionally their variants (style, weight, stretch).

6. typst update

Self-updates the Typst CLI (requires self-update feature).

Usage:

typst update [VERSION] [OPTIONS]

Arguments:

  • [VERSION]: Specific version to update to (defaults to latest)

Options:

  • --force: Allow downgrading to older versions
  • --revert: Revert to previous version before last update
  • --backup-path <FILE>: Custom backup file location

Environment Variables:

  • TYPST_UPDATE_BACKUP_PATH: Default backup path

Behavior:

  • Downloads pre-compiled binary from GitHub releases
  • Creates backup before updating
  • Supports reverting to backup

7. typst completions

Generates shell completion scripts.

Usage:

typst completions <SHELL>

Supported Shells:

  • bash
  • elvish
  • fish
  • powershell
  • zsh

Example:

# Bash
typst completions bash > ~/.local/share/bash-completion/completions/typst

# Zsh
typst completions zsh > ~/.zfunc/_typst

8. typst info

Displays environment information and configuration.

Usage:

typst info [OPTIONS]

Options:

  • --format, -f <FORMAT>: Output format (json, yaml)
  • --pretty: Pretty-print JSON output

Information Displayed:

  • Typst version and build info
  • Build settings (self-update, http-server)
  • Runtime features
  • Font configuration
  • Package paths
  • Environment variables

Global Options

These options apply to all commands:

  • --color <WHEN>: Control color output (auto, always, never)
  • --cert <PATH>: Custom CA certificate for network requests

World Arguments

These options configure the compilation environment:

Project Configuration

  • --root <DIR>: Project root for absolute paths
    • Environment variable: TYPST_ROOT

Inputs

  • --input <KEY=VALUE>: Add key-value pairs visible through sys.inputs
    • Can be specified multiple times
    • Example: --input version=1.0 --input author="John Doe"

Font Configuration

  • --font-path <DIR>: Add custom font directories (can specify multiple)
    • Environment variable: TYPST_FONT_PATHS (colon-separated on Unix, semicolon on Windows)
  • --ignore-system-fonts: Don't search system fonts
    • Environment variable: TYPST_IGNORE_SYSTEM_FONTS
  • --ignore-embedded-fonts: Don't use embedded fonts (requires embed-fonts feature)
    • Environment variable: TYPST_IGNORE_EMBEDDED_FONTS

Package Configuration

  • --package-path <DIR>: Custom local packages directory
    • Environment variable: TYPST_PACKAGE_PATH
  • --package-cache-path <DIR>: Custom package cache directory
    • Environment variable: TYPST_PACKAGE_CACHE_PATH

Timestamps

  • --creation-timestamp <UNIX_TIMESTAMP>: Document creation date as UNIX timestamp
    • Environment variable: SOURCE_DATE_EPOCH
    • Used for reproducible builds

Process Arguments

  • --jobs, -j <JOBS>: Number of parallel jobs (defaults to CPU count)
  • --features <FEATURES>: Enable experimental features (comma-separated)
    • html: Experimental HTML support
    • a11y-extras: Experimental accessibility additions
    • Environment variable: TYPST_FEATURES
  • --diagnostic-format <FORMAT>: Diagnostic format (human, short)

Environment Variables

Core Configuration

  • TYPST_CERT: Custom CA certificate path
  • TYPST_ROOT: Project root directory
  • TYPST_FEATURES: Comma-separated list of experimental features

Fonts

  • TYPST_FONT_PATHS: Custom font directories (path separator: : on Unix, ; on Windows)
  • TYPST_IGNORE_SYSTEM_FONTS: Set to ignore system fonts
  • TYPST_IGNORE_EMBEDDED_FONTS: Set to ignore embedded fonts

Packages

  • TYPST_PACKAGE_PATH: Local packages directory
  • TYPST_PACKAGE_CACHE_PATH: Package cache directory

Build Reproducibility

  • SOURCE_DATE_EPOCH: UNIX timestamp for reproducible builds

Self-Update

  • TYPST_UPDATE_BACKUP_PATH: Custom backup file location

System (Unix)

  • XDG_CACHE_HOME: Base cache directory
  • XDG_DATA_HOME: Base data directory
  • FONTCONFIG_FILE: Font configuration file
  • OPENSSL_CONF: OpenSSL configuration

Network

  • NO_COLOR: Disable colored output
  • NO_PROXY: Proxy exclusion list
  • HTTP_PROXY: HTTP proxy
  • HTTPS_PROXY: HTTPS proxy
  • ALL_PROXY: All protocols proxy

Input/Output Handling

Input Sources

  • File path: Regular file on disk
  • Stdin: Use - to read from standard input
    • Note: Output must be specified when using stdin

Output Destinations

  • File path: Regular file on disk
  • Stdout: Use - to write to standard output
    • Note: Cannot use stdout in watch mode

Multi-page Export

For PNG and SVG exports with multiple pages, use templates in output path:

  • {p}: Page number
  • {0p}: Zero-padded page number
  • {n}: Zero-padded page number (alternative)
  • {t}: Total page count

Example:

typst compile document.typ "page-{0p}-of-{t}.png"
# Produces: page-01-of-10.png, page-02-of-10.png, etc.

File Watching

Watch Behavior

  • Monitors all file dependencies
  • Automatically recompiles on changes
  • Ignores output file changes
  • Batches events within 100ms
  • Maximum batch window: 500ms
  • Poll interval for missing files: 300ms

Watch Status Messages

  • Compiling: Compilation in progress
  • Success: Compiled successfully (with duration)
  • Partial Success: Compiled with warnings (with duration)
  • Error: Compiled with errors

HTTP Server (HTML Export)

  • Serves HTML with live reload
  • Default port range: 3000-3005
  • Server-sent events for reload notifications
  • Placeholder HTML shown during initial compilation

Diagnostics

Diagnostic Formats

  • human: Full, colorful diagnostics with context (default)
  • short: Compact diagnostic format

Diagnostic Display

  • Error and warning messages
  • File locations with line/column numbers
  • Syntax highlighting of problematic code
  • Hints and suggestions
  • Trace/stacktrace information

Dependencies Tracking

Dependency Formats

JSON Format

{
  "inputs": ["file1.typ", "file2.typ"]
}

Zero Format

Paths separated by NULL bytes (\0), suitable for processing with xargs -0.

Make Format

Makefile-compatible format:

output.pdf: input1.typ input2.typ

Usage

# JSON format
typst compile main.typ --deps deps.json

# Make format
typst compile main.typ --deps deps.mk --deps-format make

# Use with build systems
make -j $(shell typst compile main.typ --deps deps.mk --deps-format make)

Performance & Optimization

Parallelization

  • Default: Uses all available CPU cores
  • Configurable via --jobs flag
  • Setting to 1 disables parallelism

Caching

  • Font discovery cached across compilations
  • Source files cached and incrementally updated
  • Export cache for unchanged image pages in watch mode
  • Comemo-based incremental compilation
  • Cache eviction after each compilation (retains 10 most recent)

Timing Analysis

Export compilation performance data:

typst compile document.typ --timings record.json

Output can be loaded into tracing tools like https://ui.perfetto.dev

In watch mode, use {n} placeholder for multiple recordings:

typst watch document.typ --timings "record-{n}.json"

Package Management

Package Specifications

  • Format: @namespace/name:version
  • Example: @preview/charged-ieee:0.1.0
  • Version optional (defaults to latest): @preview/charged-ieee

Package Sources

  • Local: Custom package path
  • Cache: Downloaded and cached packages
  • Remote: Typst package registry

Package Downloads

  • Automatic download when needed
  • Progress display with:
    • Download size and progress percentage
    • Transfer speed
    • Elapsed time and ETA
    • Downloaded amount

Exit Codes

  • 0: Success
  • Non-zero: Failure (compilation errors, missing files, etc.)

Common Workflows

Basic Compilation

# Compile to PDF
typst compile document.typ

# Compile to PNG
typst compile document.typ output.png

# Compile specific pages
typst compile document.typ output.pdf --pages 1,3-5

Watch Mode

# Watch and compile
typst watch document.typ

# Watch with HTML server
typst watch document.typ output.html

# Watch with custom port
typst watch document.typ output.html --port 3001

Working with Packages

# Initialize from template
typst init @preview/charged-ieee my-paper
cd my-paper
typst watch main.typ

Reproducible Builds

# Set fixed timestamp
typst compile document.typ --creation-timestamp 1234567890

# Or via environment variable
export SOURCE_DATE_EPOCH=1234567890
typst compile document.typ

Custom Fonts

# Use custom font directory
typst compile document.typ --font-path ./fonts

# Ignore system fonts
typst compile document.typ --font-path ./fonts --ignore-system-fonts

Querying Documents

# Query headings
typst query document.typ heading --format json

# Query with field extraction
typst query document.typ heading --field level --format json

# Query single element
typst query document.typ "#metadata((author: \"John\"))" --one

Error Handling

Common Errors

  • Input not found: File doesn't exist
  • Input outside root: File not in project root
  • Root not found: Project root doesn't exist
  • Access denied: Insufficient permissions
  • Is directory: Attempted to read directory as file
  • Invalid UTF-8: File not valid UTF-8
  • Package not found: Package doesn't exist in registry

Error Display

Errors shown with:

  • Error message in red
  • Source location
  • Relevant code snippet
  • Hints and suggestions

Best Practices

  1. Project Structure: Keep source files within a single root directory
  2. Version Control: Use --creation-timestamp for reproducible PDFs
  3. Watch Mode: Prefer typst watch over repeated typst compile
  4. Dependencies: Track dependencies for build systems integration
  5. Fonts: Use --font-path for project-specific fonts
  6. Templates: Use typst init to start new projects
  7. Outputs: Use explicit output paths for clarity
  8. Features: Only enable experimental features when needed

Platform-Specific Notes

Linux

  • Font directories: System paths + custom paths
  • Default package cache: $XDG_CACHE_HOME/typst or ~/.cache/typst
  • Default package path: $XDG_DATA_HOME/typst/packages or ~/.local/share/typst/packages

macOS

  • Font directories: System paths + custom paths
  • Default package cache: ~/Library/Caches/typst
  • Default package path: ~/Library/Application Support/typst/packages

Windows

  • Font directories: System paths + custom paths
  • Default package cache: %APPDATA%\typst\cache
  • Default package path: %APPDATA%\typst\packages
  • Path separator: ; (instead of :)