CLI Reference
The zero-native CLI provides project scaffolding, validation, packaging, and debugging tools.
Commands
| Command | Description |
|---|---|
zero-native init [path] --frontend <next|vite|react|svelte|vue> | Scaffold a new zero-native project with the specified frontend. Omit path to scaffold into the current directory. |
zero-native dev --binary <path> | Start the app with a managed frontend dev server (--binary is required) |
zero-native doctor | Check host environment, WebView, manifest, and CEF |
zero-native cef install | Download, prepare, and verify the macOS CEF runtime |
zero-native cef path | Print the default or configured CEF directory |
zero-native cef doctor | Check only the CEF layout |
zero-native validate [app.zon] | Validate app.zon against the manifest schema |
zero-native package | Package the app for distribution |
zero-native bundle-assets [app.zon] [assets] [output] | Copy frontend assets into the build output |
zero-native package-windows | Package shortcut for Windows |
zero-native package-linux | Package shortcut for Linux |
zero-native package-ios | Package shortcut for iOS |
zero-native package-android | Package shortcut for Android |
zero-native automate <command> | Interact with the automation server |
zero-native version | Print the zero-native version |
zero-native cef flags
| Flag | Description |
|---|---|
--dir | CEF install directory. Defaults to third_party/cef/macos. |
--version | CEF binary version to download. The default is zero-native's pinned tested version. |
--source | prepared or official. Defaults to prepared, which downloads zero-native's no-CMake runtime from GitHub Releases. |
--download-url | Override the prepared runtime release base URL, or the official CEF host when using --source official. |
--allow-build-tools | Allow the advanced official CEF path to invoke local build tools for libcef_dll_wrapper.a. |
--force | Redownload and replace the target directory. |
Core maintainers who need to build CEF before a zero-native runtime release exists should use tools/cef/build-from-source.sh. The CLI's default zero-native cef install path remains the no-CMake app-developer path.
zero-native package flags
| Flag | Description |
|---|---|
--target | Target platform (macos, linux, windows, ios, android) |
--manifest | Path to app.zon |
--output | Output path for the package |
--binary | Path to the built binary |
--assets | Path to frontend assets directory |
--optimize | Optimization level |
--web-engine | Temporarily override app.zon with system or chromium; Chromium is currently wired for macOS packages |
--cef-dir | Temporarily override the CEF distribution path from app.zon |
--cef-auto-install | Temporarily allow prepared CEF installation during Chromium packaging |
--signing | Signing mode: none, adhoc, or identity |
--identity | Code signing identity name |
--entitlements | Path to entitlements file |
--team-id | Apple Developer Team ID |
--archive | Create a distributable archive |
zero-native dev flags
| Flag | Description |
|---|---|
--binary (required) | Path to the compiled app binary |
--manifest | Path to app.zon (default: app.zon) |
--url | Override the dev server URL from app.zon |
--command | Override the dev server command (space-separated) |
--timeout-ms | Milliseconds to wait for the dev server (default from app.zon or 30000) |
zero-native automate subcommands
| Subcommand | Description |
|---|---|
automate list | List running automation-enabled apps |
automate snapshot | Dump current app state |
automate screenshot | Capture a screenshot |
automate reload | Reload the WebView |
automate wait | Wait for ready=true in the snapshot |
automate bridge <json> | Send a bridge command (origin zero://inline) |
Environment variables
| Variable | Description |
|---|---|
ZERO_NATIVE_FRONTEND_URL | Dev server URL (read by frontend.sourceFromEnv) |
ZERO_NATIVE_FRONTEND_ASSETS | App convention for signaling pre-built assets |
ZERO_NATIVE_LOG_DIR | Override log output directory |
ZERO_NATIVE_LOG_FORMAT | Log format: text or jsonl |