NativeScript CLI: build, deploy and live-reload native apps from a JavaScript runtime

What NativeScript is, and what the CLI is

NativeScript provides platform APIs directly to the JavaScript runtime, with strong types, for a rich TypeScript development experience. The NativeScript CLI is the command-line interface for that framework, letting you create, build and deploy NativeScript apps.

The use cases the project lists are a mix of product and learning scenarios. Building Web, iOS, Android and Vision Pro apps with a shared codebase is the core one. Building native platform apps with portable JavaScript skills is the same idea from the developer side. Augmenting JavaScript projects with platform API capabilities is the case where you have a web project and want device features. AndroidTV and Watch development, watchOS development, and learning native platforms through JavaScript understanding are the smaller ones. And there is a preview environment that lets you try APIs directly from a web browser without a platform development machine setup.

The CLI is a JavaScript project published to npm as nativescript. The install is global:

npm install -g nativescript

The install differs by platform and by how you got Node, which is the first sign of the amount of native tooling involved. On Windows, npm install nativescript -g either way. On macOS and Linux, with Node installed from nodejs.org the command is sudo npm install nativescript -g --unsafe-perm, and with Node installed via a package manager it is npm install nativescript -g without sudo and without the flag.

The reason for the difference is the postinstall step. The package has a postinstall script that runs node postinstall.js, and installing globally with sudo drops privileges that the script needs, so the unsafe-perm variant is there to work around that. The four command names in the bin field are tns, nativescript, nsc and ns, all pointing at the same bin/tns, so you can use whichever you have muscle memory for.

The five services the CLI is built from

The CLI is described as incorporating several important services, and the diagram in the README shows how they relate.

The Commands layer is pretty much what every CLI does: support for different command options, input validation and help.

The Devices Service provides the communication between NativeScript and the devices, emulators and simulators used to run and debug the app. It uses iTunes to talk to iOS and adb for Android. That is the concrete dependency on the platform tools, and it is why a device build needs the native tools installed.

The LiveSync Service redeploys applications when code changes during development, which is the part that makes the inner loop usable. Without it, every change means a full rebuild and reinstall.

The Hooks Service executes custom-written hooks in the developed application, thus modifying the build process. So a project can inject its own steps into the build rather than wrapping the CLI in a shell script.

The Platforms Service provides the app build functionality, using Gradle to build Android packages and Xcode for iOS. Those are the two build systems you would expect, and they are the reason the CLI needs a full native toolchain on the build machine rather than just Node.

The split into services is also an extension point. The repository contains extending-cli.md, extensions.md, dependency-injection.md, defining-commands.md and a contracts directory, so a plugin can add a command or a service without forking the CLI.

ns doctor, and the proxy settings you will need on a corporate network

After installing, the check is a single command:

ns doctor

The documentation says to run it to check if your system is configured properly, and that is the point at which you find out what is missing. The CLI has a doctor dependency of its own, @nativescript/doctor at 2.0.18, so the check is a first-class part of the tool rather than an afterthought.

The other thing you will configure before anything else works behind a corporate network is the proxy. The documentation has a full section on it, with a set command:

ns proxy set <Url> <Username> <Password>

The Url is required, and if you do not provide it the CLI prompts for it, with http://127.0.0.1:8888 given as an example of a valid proxy URL. The Username and Password are optional. There are also commands to display the current proxy settings and to clear them, so the whole lifecycle is covered.

That a proxy is a documented first-class concern tells you something about the audience. A native mobile toolchain downloads Android SDK components, Gradle distributions, CocoaPods and iOS runtimes, and in a locked-down network each of those is a separate thing that has to be told about the proxy. A tool that does not have a proxy command is a tool that will not work in that environment at all.

The platform requirements themselves are modest on the app side. You can target Android 4.2 or a later stable official release, and iOS 9.0 or later stable official release. The CLI itself runs on Windows, macOS or Linux, with a setup page linked for each of the three.

Extending the CLI, and the release pipeline behind it

The repository is organised for a tool that other people write plugins against, and the documentation in the repository root says so explicitly.

There is extending-cli.md and extensions.md for the plugin model, defining-commands.md for adding a command, dependency-injection.md for how the services are wired together, and a contracts directory, which is presumably where the interfaces between services are declared. There is also a PublicAPI.md, which is the sort of file that tells plugin authors what they may rely on. The packages directory and the lib directory hold the implementation, config holds the command configuration, resources holds templates and the dev directory holds development helpers.

The build is TypeScript with vitest for the tests, and the scripts show the release path. The build runs a clean of the dist directory, then tsc, then a step that generates the test dependencies, then a step that copies the assets. The test script is npm run build and vitest run, so the tests always run against a fresh build. The dev script is tsc --watch, and there is a test-watch script through a dev/tsc-to-vitest-watch.js helper.

The release build is a separate, more careful path. build.release does a clean, then compiles with tsconfig.release.json rather than the normal config, then generates the test dependencies and copies the assets with a release flag, and then runs set-ga-id.js twice, once with live and once with verify, both against the dist directory. That is the analytics identifier being baked in and then checked, so a release cannot ship with a development measurement id. pack.release then builds and runs npm pack against the dist directory.

The changelog is generated too, with conventional-changelog using the Angular preset and the -s flag, so the CHANGELOG.md is derived from commit messages rather than written by hand. The release branch is protected by a prepack guard script, guard-root-pack.js, which stops a stray pack of the repository root from being published instead of the dist directory.

There is also a substantial section on OpenSSF Scorecard maintenance, covering the branch protection check, the required branch and ruleset settings for a higher Branch-Protection and Code-Review score, keeping token permissions high, the Signed-Releases check and the Vulnerabilities check.

What the setup costs you

The first limitation is the weight of the toolchain. The CLI itself is one npm package, but to build for a device you need Node, the Android SDK with Gradle, and Xcode for iOS, and the devices service talks to adb and iTunes directly. A team that has never shipped a native app is signing up for all of that before the first build succeeds, and ns doctor is the command that tells you what is still missing.

The second limitation is that the develop loop needs a device or a simulator. The devices service exists to talk to emulators and simulators, and LiveSync redeploys the app on code changes, which is a good experience, but it is not a browser preview. The one exception the project points at is the preview environment, where you can try APIs directly from a web browser without a platform development machine setup, and that is explicitly framed as a way to explore the API documentation rather than to develop an app.

The third limitation is the version floor on the app side. Android 4.2 and iOS 9.0 are the stated minimums, which is a sensible floor, but it also means the CLI is not a tool for building for anything outside mobile. The web and Vision Pro cases in the use case list are the framework's, not the CLI's device targets.

The fourth limitation is the age of the platform support targets in the tooling, which is a broader NativeScript question rather than a CLI one, but it affects how long a project built on this stays viable.

On maintenance, the repository is not archived, the last push was on 2026-10-15, and the releases are v9.1.2 from 2026-10-01, v9.1.1 from 2026-08-31, along with a platform-specific v9.2.0-tvos.0 from 2026-09-14, which shows the CLI shipping a tvOS-flavoured prerelease line alongside the main one. The licence is Apache-2.0 with a LICENSE file at the root, and the documentation site is docs.nativescript.org.

Editorial conclusion

The NativeScript CLI suits a team that wants one JavaScript and TypeScript codebase producing native Android and iOS apps, and that values the native platform APIs being available directly in the runtime rather than through a web view. It is a poor fit if you want a quick prototype, because the toolchain is heavy and a device or emulator is needed for the develop loop, and it is a poor fit for a project that has to ship to a platform the CLI does not target. Before adopting, run ns doctor on every machine that will build, since the CLI checks the native toolchain and the output is where you find out what is missing, and read the extending-cli.md and dependency-injection.md documents in the repository if you intend to write a plugin.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. NativeScript/nativescript-cli on GitHub
3. Project website
4. README
5. Releases