CLI Reference
The naide command-line tool directly runs NAIDE files by default, and can compile, test, and manage projects.
Basic Usage
$ naide <file> # Directly execute without generating JavaScript
$ naide --compile app.naide # Opt in to JavaScript compilation/runtime
$ naide --native app.naide # Alias for the default direct execution mode
$ naide --watch app.naide # Restart native execution when the source changes
$ naide --host 0.0.0.0 app.naide # Explicitly expose a server on all interfaces
$ naide <file> -o out.mjs # Compile to file
$ naide <file> -w # Watch and restart native execution
The default runner and naide native run through NaideVM, NAIDE's direct AST interpreter, without generating JavaScript. The public embedding class is NaideVM; NativeEngine remains a compatibility alias. The native HTTP server supports JSON routes, schemas, file-backed CRUD, bearer authentication, cookie parsing, redirects, CORS, rate limits, and project-confined static files; WebSockets, GraphQL, sessions, and uploads still need naide --compile. The server binds to 127.0.0.1 by default; set --host 0.0.0.0 only when intentionally exposing it to the network. The REPL executes directly; .compile switches to JavaScript inspection mode and .eval returns to direct execution. naide check and --check use the type checker without generating JavaScript. --debug remains a compiler-backed Node.js inspector workflow. JavaScript applications can embed the interpreter with import { NaideVM, runNativeAsync } from 'naider/native'. Node.js built-ins require an explicit per-module grant, such as --node-module node:crypto; JavaScript npm packages must be listed in project dependencies first. Explicitly granted modules run with host permissions and are not sandboxed. NaideVM supports core constructs, model declarations with new, defaulted fields, custom init(params): initializers, self methods, initialized static fields, static fn/static fn.async methods and inheritance, async methods, single inheritance, and super.method() calls from instance or static overrides. Static self refers to the called model, including inherited methods; async static overrides can use await super.method(). It also supports enums (frozen objects with zero-based member values), synchronous and asynchronous generator functions, lambdas, and model methods with standalone yield statements and yield* delegation; async generators can await while producing values. Nested yield expressions are not supported yet. Async functions and async generators support for await value of iterable: for synchronous or asynchronous iterables; synchronous execution rejects this loop form. It also supports fn.async, await, await.all, task coordination (task.spawn, task.all, task.race, bounded task.map, task.sleep), and bounded asynchronous collection operations (mapAsync, filterAsync, forEachAsync) plus sequential reduceAsync. These collection operations consume synchronous or asynchronous iterables, preserve mapping/filtering order, and count input consumption against the configured step limit. Synchronous iterable helpers include map, filter, reduce, find, some, every, flatMap, unique, enumerate, zip, and sum; each and for ... of handle lists, strings, maps, sets, and generator results. Bounded/FIFO task channels use task.channel; cancellation uses task.controller(), and timeouts use task.withTimeout. Channel send/receive accept optional AbortSignals and remove cancelled waiters from the queue. Cancellation uses cooperative AbortSignals; operations that ignore a signal may continue after timeout. Runtime errors include NAIDE source locations and function/file frames when available. It supports relative .naide imports and installed NAIDE packages in node_modules when the package has a naide.pkg.json with an in-package .naide main entry. Package lookup walks parent directories; subpaths must be explicitly mapped by exact keys in the manifest's exports object to in-package .naide files. Symlink targets escaping the package are rejected. Module imports are cached; cycles are rejected. Async file I/O is available via io.readText, io.writeText, io.appendText, io.exists, and io.listDir; paths are confined to the entry file's directory. HTTP requests use http.request, http.get, and http.post with the host Fetch implementation; only HTTP(S) URLs are accepted. Network access has no host allowlist and is not an OS-level sandbox. Task scheduling is cooperative and does not provide CPU parallelism. Arbitrary JavaScript classes are not supported. Selected hot functions can use experimental, opt-in native machine-code compilation when the bridge is built on Windows x64; it is not enabled by default. Use --steps <maximum> to set an execution budget. See the measured NaideVM comparison; its fixture-specific results do not imply that the default interpreter or general applications outperform V8.
Iterable queries find/some/every and prefix operations first/take/takeWhile short-circuit and close iterators. The async equivalents are firstAsync, findAsync, someAsync, everyAsync, takeAsync, and takeWhileAsync. Counts must be non-negative safe integers, and iterator reads count toward the execution step budget.
The native runtime exposes limited host context as runtime.args, runtime.cwd, runtime.platform, runtime.arch, and runtime.exitCode. Arguments follow --; environment variables are hidden unless explicitly selected with --env NAME (repeatable), then read through runtime.env. It intentionally does not expose arbitrary process access or shell execution.
$ naide app.naide --env APP_MODE -- input.txt
# In app.naide: runtime.env.get("APP_MODE"), runtime.args
Allow one Node.js builtin explicitly with --node-module node:crypto (repeatable); imported npm packages must be declared in package.json or nidpackage.json. These modules execute with the host's permissions.
Compilation Targets
$ naide app.naide # Native interpreter (default)
$ naide --compile app.naide # JavaScript runtime (Node.js)
$ naide app.naide --target python # Compile for Python / Flask
$ naide app.naide --target bun # Compile for Bun runtime
$ naide app.naide -t py # Short alias
| Target | Output | Server |
|---|---|---|
node (compiled with --target node) | JavaScript (.mjs) | Express |
python / py | Python (.py) | Flask |
bun | JavaScript (.js) | Bun.serve() |
Type Checking
$ naide --check app.naide # Type-check only, no run
$ naide check app.naide # Same as above
Debugging
$ naide --compile app.naide --debug # Launch with Chrome DevTools
$ naide --compile app.naide -d # Short alias
Opens node --inspect-brk for step-through debugging in Chrome DevTools.
Testing
$ naide test tests.naide # Run test file
Package Ecosystem
$ naide pkg init # Initialize package.json
$ naide pkg install <name> # Install a package
$ naide pkg publish # Publish to npm
$ naide pkg list # List installed packages
Deployment
$ naide deploy # Generate Dockerfile
Generates a production Dockerfile with multi-stage build.
REPL
$ naide # Interactive REPL
NAIDE v2.0.10 REPL
> str name = "World"
> log "Hello, {name}!"
Hello, World!
All Flags
| Flag | Description |
|---|---|
-o <file> | Output compiled code to file |
-w, --watch | Watch mode |
-t, --target | Compilation target (node/python/bun/typescript/go/java/rust/cpp/c/csharp/kotlin/swift/dart/php/ruby) |
-d, --debug | Debug mode with Chrome DevTools |
--check | Type-check only |
--ast | Print AST |
--tokens | Print tokens |
-h, --help | Show help |
-v, --version | Show version |