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] [--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. Omit path to scaffold into the current directory.

--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 --binary <path> [--manifest app.zon] [--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 teaching 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.

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

`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 src/**.native markup and app.zon without building. With a fresh zig-out/model-contract.zon (refreshed by native test) it also checks bindings, iterables, and message tags against your Model/Msg and warns on model state no view uses. Without the artifact it degrades to structural checking and says so loudly: "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 honest compositions of primitives; engine controls are not on the menu (theme them through tokens instead). timeline lands as a markup template (use it via <use template="timeline" ...>), the others as Zig view functions; 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.zon] [--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.zon]

Validate app.zon against the manifest schema.

`native package`

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

Package the app for distribution. The manifest is picked up at 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.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 macOS-only chromium.
--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.

Platform shortcuts

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

Per-platform shortcuts for native package --target <platform>.

`native bundle-assets`

native bundle-assets [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 teaching 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>: Dispatch wheel input at a retained canvas widget.
automate widget-key <view-label> <key> [<text>]: Dispatch key input to the focused retained canvas widget.
automate shortcut <id>: Dispatch a shortcut command event.
automate tray-action <item-id>: Select a status-item dropdown row.
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.