CLI

The native CLI provides project scaffolding, markup validation, automation, packaging, and debugging tools. Every verb accepts --help (prints usage and exits 0); unknown flags error with the usage text.

Core loop

native init

native init [path] [--template <ts-core|zig-core>] [--frontend <native|next|vite|react|svelte|vue>] [--full]

Scaffold a new Native SDK project. The default native frontend scaffolds a native-rendered markup app with no web frontend and no build files — the CLI owns the build. The default core is TypeScript: src/core.ts, src/app.native, app.json, and no language flag anywhere else — the build detects which core the tree carries. Omit path to scaffold into the current directory.

--template

Which core to scaffold: ts-core (default) for src/core.ts, or zig-core for src/main.zig plus generated full-loop tests. Applies to the native frontend only.

--frontend

What to scaffold: native (default) for a native-rendered markup app, or next, vite, react, svelte, vue for a web frontend in a WebView shell.

--full

Also write build.zig, build.zig.zon, editor config, and CI.

native dev

native dev [dir]
native dev [dir] --core [--script msgs.ndjson] [--watch]
native dev --binary <path> [--manifest app.json] [--url <url>] [--command "<cmd>"] [--timeout-ms <n>]

Build and run the app in the current (or given) app directory — a Debug build by default, printing a one-line completion and naming any failing step. The markup hot-reload watcher and the Debug-only diagnostics are compiled in only in Debug; pass -Doptimize=... to override. Apps with a frontend dev config also get the managed dev server — see Dev Server.

--core

Run the TypeScript core's logic loop under node instead of building the app: dispatch Msgs as JSON lines on stdin, watch the committed model and effect transcript, advance a virtual clock to fire timers. This mode does not render the UI. Use native dev to run the app in a window. See TypeScript Cores.

--script

With --core: replay a newline-delimited JSON message file instead of reading stdin.

--watch

With --core: re-run the script on every src/core.ts edit.

--binary

Path to a prebuilt app binary — the legacy prebuilt-shell form: the build step is skipped and only the frontend dev flow runs. Ordinary native dev builds the app itself.

--manifest

Path to app.json or app.zon (default: auto-detected, JSON first).

--url

Override the dev server URL from the app manifest.

--command

Override the dev server command (space-separated).

--timeout-ms

Milliseconds to wait for the dev server (default from the app manifest, or 30000).

native build

native build [dir]

Build a ReleaseFast binary into zig-out/bin/, printing a one-line completion and naming any failing step.

native test

native test [dir]

Run the app's test suite, printing the zig build summary (step/test tally) plus a final native test: passed line. It also refreshes the model-contract artifact native check reads.

native check

native check [dir] [--strict]

Validate the whole tree without building the app. A TypeScript core (src/core.ts) runs the subset checker first — real tsc semantics plus the app-core rules, diagnostics verbatim — then every src/**.native markup file and the app manifest are checked as before. With a fresh model contract (zig-out/model-contract.zon, refreshed by native test) it also checks bindings, iterables, and message tags against your Model/Msg — for a TypeScript core, against its model contract — and warns on model state no view uses. Without the artifact it degrades to structural checking and says so: "model contract: not yet built - bindings checked structurally only; run native test to enable typed checks". Markup accessibility findings are reported per file in full, and a failing src/*.native file that no Zig source embeds gets a leftover-file hint.

--strict

Fail on warnings.

App lifecycle

native eject

native eject [dir]

Write an owned build.zig/build.zig.zon into the app (once); the verbs then drive your files via zig build. Ejecting is only for owning the build files — it is never a prerequisite: zero-config apps build, test, and package directly (native package works on the zero-config build as-is).

native eject component

native eject component <name> [dir]

Write an owned copy of a library composite into src/components/ (once, never overwriting — ejecting again errors with the file to delete first). Ejectable today: stepper, timeline, timeline-item — the library views that are compositions of primitives; engine controls are not on the menu (theme them through tokens instead). TypeScript apps receive Native markup templates through <import> and <use>; Zig-core apps receive a compatible Zig view when one exists, while components without a Zig form are rejected with a clear message. Each file opens with a header comment walking through the call-site migration, and each builds a widget tree identical to its library form at the moment of ejection. Unknown names get a did-you-mean plus the full ejectable list. See Building Components.

native doctor

native doctor [--strict] [--manifest app.json] [--web-engine system|chromium] [--cef-dir path] [--cef-auto-install]

Check host environment, WebView, manifest, and CEF. See native doctor for what each check means.

native validate

native validate [app.json|app.zon]

Validate app.json or app.zon against the same manifest contract.

native package

native package [--target <macos|linux|windows|ios|android>] [flags]

Package the app for distribution. The manifest is picked up at app.json (falling back to app.zon) and the binary at zig-out/bin/<name> automatically; the flags below override.

--target

Target platform (macos, linux, windows, ios, android).

--manifest

Path to app.json or 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 the app manifest with system or macOS-only chromium.

--web-layer

Override the app manifest's webview_layer with auto, include, or exclude — the same precedence as -Dweb-layer in the build graph. zig build package passes the graph's resolved decision here automatically so the package always matches the built executable.

--cef-dir

Temporarily override the CEF distribution path from the app manifest.

--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.

--notarize

Submit the final macOS artifact to Apple's notary service, then staple and validate the accepted ticket. Requires identity signing.

--notary-profile

Name of a notarytool Keychain profile created with xcrun notarytool store-credentials.

--archive

Create a distributable archive. On macOS this is a styled DMG with the app, an Applications alias, a generated or custom background, and the Finder layout declared by the app manifest.

Platform shortcuts

native package-windows [--output path] [--binary path] [--service-binary path]
native package-linux [--output path] [--binary path] [--service-binary path]
native package-ios [--output path] [--binary path]
native package-android [--output path] [--binary path]

Per-platform shortcuts for native package --target <platform>. The desktop shortcuts use an explicit --service-binary when supplied; otherwise, service-bearing projects discover the normal zig-out/bin/<app>_services[.exe] build output just like the canonical command.

native bundle-assets

native bundle-assets [app.json|app.zon] [assets] [output]

Copy frontend assets into the build output.

Tooling

native markup

native markup check <file.native> [more files...] [--strict]
native markup dump <file.native> [--out doc.nsui]
native markup lsp

Work with Native markup files directly, outside the app verbs.

markup check

Validate Native markup without building; errors carry file:line:column and a diagnostic message. Run inside an app directory it picks up a fresh model contract the same way native check does; --strict promotes warnings to failures.

markup dump

Resolve and validate a view, encode the canonical NSUI binary, and print the JSON inspection view derived from the decoded binary; --out also writes the .nsui artifact.

markup lsp

Run the markup language server (diagnostics, completion, hover) for editor integration.

native automate

native automate <command>

Interact with the automation server of a running automation-enabled app. See Automation for the full workflow.

automate list

List running automation-enabled apps.

automate snapshot

Dump current app state.

automate screenshot <view-label> [<scale>]

Render a gpu_surface view's canvas to screenshot-<view-label>.png through the deterministic CPU reference renderer.

automate reload

Reload the WebView.

automate resize <width> <height> [<scale>]

Dispatch a main-window resize event.

automate menu-command <id>

Dispatch a menu command event.

automate native-command <id> [<view-label>]

Dispatch a native view command event.

automate widget-action <view-label> <widget-id> <action> [<value>]

Invoke a retained canvas widget action.

automate widget-click <view-label> <widget-id>

Dispatch a pointer click at a retained canvas widget.

automate widget-hold <view-label> <widget-id>

Press-and-hold a retained canvas widget (drives on_hold).

automate widget-context-press <view-label> <widget-id>

Secondary-click a retained canvas widget (context menu, or on_hold when none).

automate widget-context-menu <view-label> <widget-id> <item-index>

Invoke a widget's declared context-menu item by index — the snapshot lists each widget's items in order.

automate widget-drag <view-label> <widget-id> <start-x-ratio> <end-x-ratio> [<start-y-ratio> <end-y-ratio>]

Dispatch pointer down/drag/up across a retained canvas widget.

automate widget-wheel <view-label> <widget-id> <delta-y> [<delta-x>]

Dispatch wheel input at a retained canvas widget; the optional delta-x scrolls the horizontal axis (each axis routes to the nearest region that scrolls it).

automate widget-key <view-label> <key> [<text>]

Dispatch key input to the focused retained canvas widget.

automate widget-pinch <view-label> <scale> [<x> <y>]

Dispatch a trackpad pinch gesture at a gpu-surface view (scale is the final multiplicative zoom for the gesture; the anchor point defaults to the view center).

automate shortcut <id>

Dispatch a shortcut command event.

automate tray-action <item-id> / automate tray-action <status-item-id> <item-id>

Select a status-item dropdown row; the one-id shorthand targets primary status item #1.

automate focus <view-label>

Focus a native or WebView-backed view.

automate focus-next / automate focus-previous

Move focus through visible, enabled views.

automate wait

Wait for ready=true in the snapshot.

automate assert [--absent] [--timeout-ms <n>] <pattern>...

Poll the snapshot until every regex pattern matches (or, with --absent, until none match); on timeout, prints the missing patterns plus the snapshot tail and exits non-zero.

automate bridge <json>

Send a bridge command (origin zero://inline).

native skills

native skills list
native skills get <name> [--full]
native skills get --all [--full]

List and print the built-in AI agent skills the CLI ships — the version-matched content the npx skills add vercel-labs/native discovery skill loads from. See Agent Skills for the one-command agent install, what each skill covers, and how to deliver one to an agent.

skills list

List built-in skills served by the installed CLI.

skills get <name>

Output a skill's content (for example skills get core or skills get native-ui).

skills get --all

Output every non-hidden skill.

--full

Also include a skill's reference and template files when present.

native cef

native cef install|path|doctor [--dir path] [--version version] [--source prepared|official] [--force]

Manage the macOS CEF runtime for Chromium-engine apps.

cef install

Download, prepare, and verify the macOS CEF runtime.

cef path

Print the default or configured CEF directory.

cef doctor

Check only the CEF layout.

--dir

CEF install directory. Defaults to the host platform directory under third_party/cef.

--version

CEF binary version to download. The default is Native SDK's pinned tested version.

--source

prepared or official. Defaults to prepared, which downloads Native SDK'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.

--force

Redownload and replace the target directory.

Core maintainers who need to build CEF before a Native SDK runtime release exists should use tools/cef/build-from-source.sh. The CLI's default native cef install path remains the no-CMake app-developer path.

native version

native version

Print the native version.

Environment variables

NATIVE_SDK_FRONTEND_URL

Dev server URL (read by frontend.sourceFromEnv).

NATIVE_SDK_FRONTEND_ASSETS

App convention for signaling pre-built assets.

NATIVE_SDK_LOG_DIR

Override log output directory.

NATIVE_SDK_LOG_FORMAT

Log format: text or jsonl.