NativeScript Command-Line Interface
Get it using:
npm install nativescript@next -g
The NativeScript CLI lets you create, build, and deploy NativeScript-based projects on iOS and Android devices.
- What is NativeScript
- How the NativeScript CLI works
- Supported Platforms
- System Requirements
- Quick Start
- Extending the CLI
- Known Issues
- How to Contribute
- How to Build
- Get Help
What is NativeScript
To learn more about NativeScript, you can check the following resources:
- The NativeScript web page
- NativeScript - a Technical Overview
- Development with NativeScript
- Announcing NativeScript - cross-platform framework for building native mobile applications
- The NativeScript Documentation repo and Documentation portal
- The NativeScript FAQ
- On NativeScript for Android
How the NativeScript CLI works
The NativeScript CLI is the command-line interface for interacting with NativeScript. It incorporates several important services. Consider the following diagram:
- Commands - pretty much what every CLI does - support of different command options, input validation and help
- Devices Service - provides the communication between NativeScript and devices/emulators/simulators used to run/debug the app. Uses iTunes to talk to iOS and adb for Android
- LiveSync Service - redeploys applications when code changes during development
- Hooks Service - executes custom-written hooks in developed application, thus modifying the build process
- Platforms Service - provides app build functionalities, uses Gradle to build Android packages and Xcode for iOS.
With the NativeScript CLI, you can target the following mobile platforms.
- Android 4.2 or a later stable official release
- iOS 7.0 or later stable official release
You can install and run the NativeScript CLI on Windows, macOS or Linux.
Install the NativeScript CLI
The NativeScript CLI is available for installing as an npm package.
In the command prompt, run the following command.
|OS||Node.js installed from http://nodejs.org/||Node.js installed via package manager|
To check if your system is configured properly, run the following command.
Configure Proxy Settings
If you are working with the NativeScript CLI behind a web proxy, you need to configure your proxy settings.
Set Proxy Settings
tns proxy set <Url> <Username> <Password>
(Required) The full URL of the proxy. The
<Url>attribute is required and if you do not provide it when running the command, the NativeScript CLI will prompt you to provide it. An example of a valid proxy URL is
(Optional) The credentials for the proxy. The
<Password>attributes are optional, however, if you choose to provide them, you must provide both.
--insecureflag allows you to perform insecure SSL connections and transfers. This option is useful when your proxy does not have a CA certificate or the certificate is no longer valid.
- You can provide the
<Password>attributes only on Windows systems.
- Proxy settings for the npm and the Android Gradle need to be configured separately. For more information, see the following articles:
Display Current Proxy Settings
Clear Proxy Settings
tns proxy clear
- The Commands
- Create Project
- Add Platforms
- Develop Your Project
- Prepare for Build
- Build Your Project
- Deploy Your Project
- Run Your Project
tns help to view all available commands in the browser. Run
tns help <Command> to view more information about a selected command in the browser.
tns --help opens console help, where help information is shown in the console.
tns create MyApp
To create a new cross-platform project from the default TypeScript or Angular template, use the
template option followed by either
tns create MyApp --template typescript tns create MyApp --template angular
Or you can simply use the shorthand
tns create MyApp --tsc tns create MyApp --ng
template option you can also specify a local or a remote path to the template that you want to use to create your project.
tns create MyApp --template https://github.com/NativeScript/template-hello-world.git
To create a new cross-platform project from an existing NativeScript project, run the following command.
tns create MyApp --copy-from <Directory>
<Directory> is the complete path to the directory that contains your existing project. You can use any NativeScript project, created with the Telerik AppBuilder clients.
The NativeScript CLI creates a new project and sets the application identifier to
The CLI places the project in a new directory in the current directory. The newly created directory has the following structure.
MyApp/ ├── app │ ├── app.css │ ├── app.js │ ├── bootstrap.js │ ├── main-page.js │ ├── main-page.xml │ ├── App_Resources │ │ └── ... │ └── tns_modules │ └── ... └── platforms └── ...
appdirectory is the development space for your application. You should modify all common and platform-specific code within this directory. When you run
prepare <Platform>, the NativeScript CLI copies relevant content to the platform-specific folders for each target platform.
platformsdirectory is created empty. When you add a target platform to your project, the NativeScript CLI creates a new subdirectory with the platform name. The subdirectory contains the ready-to-build resources of your app. When you run
prepare <Platform>, the NativeScript CLI copies relevant content from the
appdirectory to the platform-specific subdirectory for each target platform.
After you have created your project, you can start adding target platforms to it. To be able to build your project into an application package for a selected target platform, you need to add the platform to your project first. Currently, you can target Android and iOS with your NativeScript projects.
Navigate to the directory that contains your newly created project and run the following commands.
tns platform add android tns platform add ios
platform add creates the
android and the
ios subdirectories in the
platforms directory. These subdirectories have the platform-specific project structure required for native development with the native SDKs for the platform.
... platforms/ |-- android/ |-- |-- assets/ |-- |-- gen/ |-- |-- libs/ |-- |-- node_modules/ |-- |-- res/ |-- |-- src/ |-- |-- .project |-- |-- AndroidManifest.xml |-- |-- build.xml |-- |-- local.properties |-- |-- proguard-project.txt |-- `-- project.properties |-- ios/ |-- |-- libTNSBridge.a |-- |-- node_modules `-- |-- MyApp/ `-- MyApp.xcodeproj ...
For more information about the structure of Android native projects, see Android Projects.
For more information about the structure of iOS native projects, see Code Organization in Xcode Projects.
TIP: The NativeScript team provides experimental support for the latest versions of iOS and Android. You can choose which platform runtime to use in your project by running
tns platform add <platform>@<Version>
To list all available versions for android, run $ npm view tns-android versions
To list only experimental versions for android, run $ npm view tns-android dist-tags To list all available versions for ios, run $ npm view tns-ios versions
To list only experimental versions for ios, run $ npm view tns-ios dist-tags
Develop Your Project
Development with NativeScript
For more information about working with NativeScript, see the following resources.
app directory in the root of the project is the development space for your project. Place all your common and platform-specific code in this directory. When you run
prepare <Platform>, the NativeScript CLI copies relevant content to the platform-specific folders for each target platform.
app directory, you can use platform-specific files to provide customized functionality and design for each target platform. To indicate that a file is platform-specific, make sure that the file name is in the following format:
name.android.extension. For example:
You can develop shared functionality or design in common files. To indicate that a file is common, make sure that the file name does not contain a
IMPORTANT: Avoid editing files located in the
platformssubdirectory because the NativeScript CLI overrides such files during the
prepare <Platform>using the contents of the
Modifying Configuration Files
The NativeScript CLI respects any platform configuration files placed inside
app/App_Resources. Those files are respectively
app/App_Resources/AndroidManifest.xml for Android and
app/App_Resources/Info.plist for iOS.
Additionaly, you can modify
app/App_Resources/app.gradle for adding/removing additional build properties for iOS and Android, respectively.
Modifying Entitlements File (iOS only)
To specify which Capabilities are required by your App - Maps, Push Notifications, Wallet and etc. you can add or edit the
app.entitlements file placed inside
app/App_Resources/iOS. When building the project, the default
app/App_Resources/iOS/app.entitlements file gets merged with all Plugins entitlement files and a new
yourAppName.entitlements is created in the platforms directory. The path would be
app/platforms/ios/<application name>/<application name>.entitlements and will be linked in the
You can always override the generated entitlements file, by pointing to your own entitlements file by setting the
CODE_SIGN_ENTITLEMENTS property in the
Prepare for Build
When you run
build, the NativeScript CLI uses the resources from the platform-specific subdirectory in the
platforms directory. To populate the platform-specific subdirectory with the correct application assets, you need to run
tns prepare android tns prepare ios
prepare <Platform> takes content from
app, analyzes it and copies it to the platform-specific subdirectory in
platforms. This operation copies common and relevant platform-specific content that applies to the selected platform. This ensures that your Android or iOS application contain only the correct assets.
Keep in mind that
prepare overrides changes made to the platform-specific subdirectory in
platforms. For more information, see Development in platforms.
Build Your Project
After you have prepared your project, you can build it for your target mobile platforms.
tns build android tns build ios
The NativeScript CLI calls the SDK for the selected target platform and uses it to build your app locally.
When you build for Android, the NativeScript CLI saves the application package as an
When you build for iOS, the NativeScript CLI will either build for a device, if there's a device attached, or for the native emulator if there are no devices attached. To trigger a native emulator build when a device is attached, set the
The native emulator build is saved as an
emulator. The device build is saved as an
IMPORTANT: To build your app for an iOS device, you must configure a valid certificate and provisioning profile pair, and have that pair present on your system for code signing your application package. For more information, see iOS Code Signing - A Complete Walkthrough.
Deploy Your Project
You can test your work in progress on connected Android or iOS devices.
To verify that the NativeScript CLI recognizes your connected devices, run the following command.
The NativeScript CLI lists all connected physical devices and running Android Virtual Devices.
After you have listed the available devices, you can deploy your app on all devices from the selected target platform.
tns deploy android tns deploy ios
The NativeScript CLI calls the SDK for the selected target platform and uses it to build your app locally. After the build is complete, the NativeScript CLI downloads and installs the application package on your connected devices.
On Android devices, the app runs automatically.
On iOS devices, the app does not run automatically. To run the app, tap the app icon.
IMPORTANT: To deploy your app on iOS devices, you need to configure a valid pair of certificate and provisioning profile for code signing your application package. For more information, see iOS Code Signing - A Complete Walkthrough.
Emulate Your Project
If you do not have any physical devices on which to test your app or if you have not configured any certificates and provisioning profiles for iOS, you can run your app in the native emulator of your target platform.
tns run android --emulator tns run ios --emulator
This operation calls the SDK for the selected target platform, builds your app locally, launches the native device emulator for the selected target platform, and runs your project on the virtual device.
For Android, the NativeScript CLI runs your app in the earliest created virtual device or the currently running Android Virtual Device. Before running your app in the Android native emulator, make sure that you have configured at least one virtual device in the Android Virtual Device manager.
For iOS, the NativeScript CLI runs your app in the iOS Simulator.
Run Your Project
You can quickly run your app on connected devices, including all running Android Virtual Devices. The following command is shorthand for
tns run android tns run ios
Extending the CLI
The NativeScript CLI lets you extend its behavior and customize it to fit your needs by using hooks.
When you run one of the extendable commands (for example,
tns build), the CLI checks for hooks and executes them. Plugins can also use hooks to control the compilation of the application package.
For more information, see the Extending the CLI document
If the NativeScript CLI does not behave as expected, you might be facing a configuration issue. For example, a missing
JAVA path. To check if your system is configured properly for the NativeScript CLI, run the following command.
This command prints warnings about current configuration issues and provides basic information about how to resolve them.
You cannot synchronize changes to apps on Android 4.3 devices and on some Samsung devices using the
Workaround: Upgrade to a later version of Android to be able to use the
livesynccommand. If you need to develop for Android 4.3 devices, re-build and re-deploy your app to get your latest changes on device.
On macOS systems with configured firewall or web proxy, when you run a command, the operation might not release the command line and you might not be able to run other commands until you break the current operation.
If you have enabled feature usage tracking for the NativeScript CLI, but you have not authenticated with the firewall or web proxy on your macOS system, the NativeScript CLI might not release the command line after you run a command. To continue working with the NativeScript CLI, you need to break the current operation by pressing
Workaround: Authenticate with the firewall or web proxy.
- Close the terminal.
- Run Safari.
- Attempt to open a web page.
- Provide your authentication credentials for accessing the Internet.
- Run the terminal and continue working with the NativeScript CLI.
How to Contribute
To learn how to log a bug that you just discovered, click here.
To learn how to suggest a new feature or improvement, click here.
To learn how to contribute to the code base, click here.
How to Build
git clone https://github.com/NativeScript/nativescript-cli cd nativescript-cli npm run setup
To use the locally built CLI instead
tns you can call
PATH_TO_CLI_FOLDER/bin/tns. For example:
PATH_TO_CLI_FOLDER/bin/tns run ios|android
Please, use github issues strictly for reporting bugs or requesting features. For general NativeScript questions and support, check out the NativeScript community forum or ask our experts in NativeScript community Slack channel.
This software is licensed under the Apache 2.0 license, quoted here.