Complete reference for all Perry CLI flags.
Available on all commands:
Flag Description
--format text|jsonOutput format (default: text) -v, --verboseIncrease verbosity (repeatable: -v, -vv, -vvv) -q, --quietSuppress non-error output --no-colorDisable ANSI color codes
Use --target to cross-compile:
Target Platform Notes
(none) Current platform Default behavior ios-simulatoriOS Simulator ARM64 simulator binary iosiOS Device ARM64 device binary visionos-simulatorvisionOS Simulator Apple Vision Pro simulator build visionosvisionOS Device Apple Vision Pro device build androidAndroid ARM64/ARMv7 ios-widgetiOS Widget WidgetKit extension (requires --app-bundle-id) ios-widget-simulatoriOS Widget (Sim) Widget for simulator watchos-widgetwatchOS Complication WidgetKit extension for Apple Watch watchos-widget-simulatorwatchOS Widget (Sim) Widget for watchOS simulator android-widgetAndroid Widget Android App Widget (AppWidgetProvider) wearos-tileWear OS Tile Wear OS Tile (TileService) wasmWebAssembly Self-contained HTML with WASM or raw .wasm binary webWeb Outputs HTML file with JS windowsWindows Win32 executable linuxLinux GTK4 executable
Use --output-type to change what’s produced:
Type Description
executableStandalone binary (default) dylibShared library (.dylib/.so) for plugins
Flag Description
--print-hirPrint HIR (intermediate representation) to stdout --no-linkProduce .o object file only, skip linking --keep-intermediatesKeep .o and .asm intermediate files
Flag Description
--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.
Flag Description
--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)
Flag Description
--enable-js-runtimeEnable V8 JavaScript runtime for unsupported npm packages --type-checkEnable type checking via tsgo IPC
Variable Description
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)
[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"
[apple]
team_id = "XXXXXXXXXX"
signing_identity = "Developer ID Application: Your Name"
[android]
keystore_path = "/path/to/keystore.jks"
key_alias = "my-key"
# 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