@octane-xplat/cli

Run your app, inspect changes with your agent, and check builds for the targets you plan to ship.

Status: 0.x — the API surface is still moving. iOS/Android targets need the NativeScript toolchain (Xcode/JDK + ns).

For a new app, start with the creator. The CLI runs configured web, iOS, and Android targets, plus opt-in experimental macOS, Windows, and Linux apps. The Windows scaffold has passed bundle generation only; launch and runtime behavior remain unverified. See target support.

For an existing app:

pnpm add -D @octane-xplat/cli

pnpm xplat dev          # pick available targets
pnpm xplat add ios      # enable a platform skipped at create time
pnpm xplat build        # production builds
pnpm xplat build -t macos # experimental AppKit .app + .dmg (Apple Silicon)
pnpm xplat build -t linux # experimental GTK/WebKit app directory + tar archive
pnpm xplat doctor       # environment + framework patch check
pnpm xplat typecheck    # web + native tsconfigs
pnpm xplat patches apply  # install the framework's pnpm patch set into this app
pnpm xplat patches check  # verify the patch set is registered and unmodified
pnpm xplat fonts add ./Inter.ttf      # .ttf/.otf/.woff/.woff2 → src/fonts + fonts.css + --font-* token
pnpm xplat fonts add @fontsource-variable/inter --install  # Fontsource package

The framework carries a small set of upstream fixes as pnpm patchedDependencies (packages/cli/patches/ + manifest in the published package). pnpm only honors them at an app's workspace root. For existing apps, xplat patches apply copies the .patch files into <app>/patches/ and merges the block into the app's pnpm-workspace.yaml (or pnpm.patchedDependencies in package.json). Fresh apps from create-octane-xplat fetch the dependency-free @octane-xplat/patches package through pnpm configDependencies; their patch paths point into node_modules/.pnpm-config/.

pnpm xplat patches apply
pnpm xplat patches check

The scaffolded app's pnpm dev / pnpm build / pnpm dev:ios scripts drive the supported targets directly; xplat is the multi-target front end. The experimental macOS target is configured by the app and packaged by xplat.

pnpm dev
pnpm build
pnpm dev:ios

Linux packaging and its required manifest settings are documented in Package a Linux app. The CLI ships the GJS host; Linux users supply the GTK/WebKit system runtime.

Also exports the native vite preset — it absorbs the app-owned native config (renderer rules, octane→universal alias, .ios/.android extension chain, HMR watchdog, px→dip rewrite):

// vite.config.native.mts
import { defineConfig } from 'vite'
import { xplatNative } from '@octane-xplat/cli/vite'

export default defineConfig(({ mode }) => xplatNative(mode))

Docs: Get a working app and iterate — agents: llms.txt

The experimental AppKit preset is exported separately from @octane-xplat/cli/macos/vite:

import { defineConfig } from 'vite'
import { xplatMacOS } from '@octane-xplat/cli/macos/vite'

export default defineConfig(({ mode }) => xplatMacOS(mode))

It resolves the app's @octane-xplat/macos-renderer package and installed Octane compiler. See AppKit renderer setup for application dependencies, root ownership, fonts, and development bundles.

import { xplatMacOS } from '@octane-xplat/cli/macos/vite'

export default await xplatMacOS('production', { entry: 'src/main.mjs' })