Compiler Flags

Complete reference for all Perry CLI flags.

Global Flags

Available on all commands:

Compilation Targets

Use --target to cross-compile:

Output Types

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

Embedding Assets

Bake static files (an SPA dist/, images, JSON, fonts, …) into the standalone executable so it runs with no external files on disk (#5731).

vite build
perry compile server.ts --embed "./dist/**" -o myapp
./myapp   # serves dist/ from memory — no dist/ folder needed

Embedded files are reachable at runtime three ways:

import { embeddedFiles, readEmbedded, isStandaloneExecutable } from "perry";
import { readFileSync } from "fs";

for (const f of embeddedFiles()) {
  // f.name (e.g. "dist/index.html"), f.size, f.type (MIME)
  app.get("/" + f.name, (_, reply) => reply.type(f.type).send(readEmbedded(f.name)));
}

// or via node:fs at the `$perryfs/<path>` virtual path:
const html = readFileSync("$perryfs/dist/index.html", "utf8");

embeddedFiles() is a function (not a bare value like Bun’s embeddedFiles) so that array methods dispatch on its result. readEmbedded(path) and node:fs accept either the $perryfs/<path> virtual path or the embed-relative key.

Note node:fs consults the embedded registry before disk, and a bare embed-relative key matches too — so readFileSync("dist/index.html") returns the embedded bytes even if a dist/index.html exists on disk next to the binary. Read a real on-disk file by absolute path, and use the explicit $perryfs/<path> form when you specifically mean the embedded copy.

Embedding currently requires a Unix-like host toolchain (macOS/Linux); on a Windows host --embed errors out. Cross-target / Windows embedding is a tracked follow-up.

Debug Flags

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

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

Testing Flags

Runtime Flags

Environment Variables

Configuration Files

perry.toml (project)

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

[build]
out_dir = "build"

[compile]
# Embed static assets into the standalone executable (same as repeated --embed).
embed = ["./dist/**"]

[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

• Commands — All CLI commands
• Platform Overview — Platform targets