Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Compiler Flags

Complete reference for all Perry CLI flags.

Global Flags

Available on all commands:

FlagDescription
--format text|jsonOutput format (default: text)
-v, --verboseIncrease verbosity (repeatable: -v, -vv, -vvv)
-q, --quietSuppress non-error output
--no-colorDisable ANSI color codes

Compilation Targets

Use --target to cross-compile:

TargetPlatformNotes
(none)Current platformDefault behavior
ios-simulatoriOS SimulatorARM64 simulator binary
iosiOS DeviceARM64 device binary
visionos-simulatorvisionOS SimulatorApple Vision Pro simulator build
visionosvisionOS DeviceApple Vision Pro device build
androidAndroidARM64/ARMv7
ios-widgetiOS WidgetWidgetKit extension (requires --app-bundle-id)
ios-widget-simulatoriOS Widget (Sim)Widget for simulator
watchos-widgetwatchOS ComplicationWidgetKit extension for Apple Watch
watchos-widget-simulatorwatchOS Widget (Sim)Widget for watchOS simulator
android-widgetAndroid WidgetAndroid App Widget (AppWidgetProvider)
wearos-tileWear OS TileWear OS Tile (TileService)
wasmWebAssemblySelf-contained HTML with WASM or raw .wasm binary
webWebOutputs HTML file with JS
windowsWindowsWin32/GDI executable (default Windows backend)
windows-winuiWindows (Fluent)Opt-in WinUI 3 / Fluent backend (#4680). Scaffold: currently renders via Win32 while the XAML widget mapping lands incrementally; selects the perry-ui-windows-winui static library. Build that lib first: cargo build --release -p perry-ui-windows-winui.
linuxLinuxGTK4 executable

Output Types

Use --output-type to change what’s produced:

TypeDescription
executableStandalone binary (default)
dylibShared library (.dylib/.so) for plugins

Debug Flags

FlagDescription
--print-hirPrint HIR (intermediate representation) to stdout
--trace <STAGES>Dump IR at one or more pipeline stages. Comma-separated: hir (post-transform HIR), llvm (per-module .ll into .perry-trace/llvm/), or all
--focus <NAME>Restrict --trace hir to functions/methods/classes whose name contains NAME, suppressing import/export/init noise. Implies --trace hir if no stage is given
--no-linkProduce .o object file only, skip linking
--no-codegenSkip the package.json perry.codegen build-time steps (also PERRY_SKIP_CODEGEN=1). See Project Configuration
--keep-intermediatesKeep .o and .asm intermediate files

The --trace/--focus pair localizes “compiled to the wrong thing” bugs: perry compile foo.ts --trace hir,llvm --focus parseRow dumps just the parseRow function’s lowered HIR and the module’s LLVM IR, so you can see which stage corrupted it without scrolling a full-module dump. --trace llvm forces a full recompile (the object cache otherwise skips codegen for unchanged modules, leaving the trace dir empty).

Output Optimization

FlagDescription
--minifyMinify and obfuscate output (auto-enabled for --target web)

Minification strips comments, collapses whitespace, and mangles local variable/parameter/non-exported function names for smaller output.

Testing Flags

FlagDescription
--enable-geisterhandEmbed the Geisterhand HTTP server for programmatic UI testing (default port 7676)
--geisterhand-port <PORT>Set a custom port for the Geisterhand server (implies --enable-geisterhand)

Runtime Flags

FlagDescription
--enable-js-runtimeEnable V8 JavaScript runtime for unsupported npm packages
--enable-wasm-runtimeForce-link the wasmi WebAssembly host runtime (auto-detected when WebAssembly.* is referenced; needed only when loading via dlopen / FFI without a static reference)
--type-checkEnable type checking via tsgo IPC

Environment Variables

VariableDescription
PERRY_LICENSE_KEYPerry Hub license key for perry publish
PERRY_APPLE_CERTIFICATE_PASSWORDPassword for .p12 certificate
PERRY_NO_UPDATE_CHECK=1Disable automatic update checks
PERRY_UPDATE_SERVERCustom update server URL
CI=trueAuto-skip update checks (set by most CI systems)
RUST_LOGDebug logging level (debug, info, trace)

Configuration Files

perry.toml (project)

[project]
name = "my-app"
entry = "src/main.ts"
version = "1.0.0"

[build]
out_dir = "build"

[app]
name = "My App"
description = "A Perry application"

[macos]
bundle_id = "com.example.myapp"
category = "public.app-category.developer-tools"
minimum_os = "13.0"
distribute = "notarize"  # "appstore", "notarize", or "both"

[ios]
bundle_id = "com.example.myapp"
deployment_target = "16.0"
device_family = ["iphone", "ipad"]

[android]
package_name = "com.example.myapp"
min_sdk = 26
target_sdk = 34

[linux]
format = "appimage"  # "appimage", "deb", "rpm"
category = "Development"

~/.perry/config.toml (global)

[apple]
team_id = "XXXXXXXXXX"
signing_identity = "Developer ID Application: Your Name"

[android]
keystore_path = "/path/to/keystore.jks"
key_alias = "my-key"

Examples

# Simple CLI program
perry main.ts -o app

# iOS app for simulator
perry app.ts -o app --target ios-simulator

# visionOS app for simulator
perry app.ts -o app --target visionos-simulator

# Web app (WASM with DOM bridge — alias: --target wasm)
perry app.ts -o app --target web

# Plugin shared library
perry plugin.ts --output-type dylib -o plugin.dylib

# iOS widget with bundle ID
perry widget.ts --target ios-widget --app-bundle-id com.example.app

# Debug compilation
perry app.ts --print-hir 2>&1 | less

# Verbose compilation
perry compile app.ts -o app -vvv

# Type-checked compilation
perry app.ts -o app --type-check

# Raw WASM binary (no HTML wrapper)
perry app.ts -o app.wasm --target wasm

# Minified web output (compresses embedded JS bridge)
perry app.ts -o app --target web --minify

Next Steps