{"id":13555728,"url":"https://github.com/NativeScript/nativescript-cli","last_synced_at":"2025-04-03T08:31:58.563Z","repository":{"id":18211590,"uuid":"21347346","full_name":"NativeScript/nativescript-cli","owner":"NativeScript","description":"Command-line interface for building NativeScript apps","archived":false,"fork":false,"pushed_at":"2024-08-28T12:33:02.000Z","size":176399,"stargazers_count":1036,"open_issues_count":369,"forks_count":195,"subscribers_count":86,"default_branch":"main","last_synced_at":"2024-10-29T15:25:37.652Z","etag":null,"topics":["android","cli","cross-platform","hacktoberfest","ios","mobile","nativescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/nativescript","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NativeScript.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"NativeScript","open_collective":"nativescript"}},"created_at":"2014-06-30T10:21:20.000Z","updated_at":"2024-10-25T15:07:05.000Z","dependencies_parsed_at":"2023-02-12T04:01:33.257Z","dependency_job_id":"d9b88a87-a152-40ec-9c2c-641dd528d816","html_url":"https://github.com/NativeScript/nativescript-cli","commit_stats":{"total_commits":4247,"total_committers":149,"mean_commits":"28.503355704697988","dds":0.8453025665175418,"last_synced_commit":"bf0e6202d1c82d7b24e0db928fe033aad4b14760"},"previous_names":[],"tags_count":309,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NativeScript%2Fnativescript-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NativeScript%2Fnativescript-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NativeScript%2Fnativescript-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NativeScript%2Fnativescript-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NativeScript","download_url":"https://codeload.github.com/NativeScript/nativescript-cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246707215,"owners_count":20820887,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","cli","cross-platform","hacktoberfest","ios","mobile","nativescript"],"created_at":"2024-08-01T12:03:22.843Z","updated_at":"2025-04-03T08:31:58.518Z","avatar_url":"https://github.com/NativeScript.png","language":"JavaScript","readme":"\n\u003ch1 id=\"nativescript-command-line-interface\" align=\"center\"\u003e\n  \u003cbr\u003e\n  \u003ca href=\"https://www.npmjs.com/package/nativescript\"\u003e\u003cimg src=\"https://art.nativescript.org/logo/export/NativeScript_Logo_Wide_White_Blue_Rounded_Blue.svg\" alt=\"Nativescript Logo\" width=\"200\"\u003e\u003c/a\u003e\n  \u003cbr\u003e\n\t  \u003cbr\u003e\n   NativeScript Command-Line Interface\n  \u003cbr\u003e\n\u003c/h1\u003e\n\n\u003ch4 align=\"center\"\u003eThe NativeScript CLI lets you create, build, and deploy \u003ca href=\"https://docs.nativescript.org/\" target=\"_blank\"\u003eNativeScript\u003c/a\u003e apps.\u003c/h4\u003e\n  \u003c/a\u003e\n\u003c/h4\u003e\n\n---\n\n[![nativescript -\u003e npm](https://github.com/NativeScript/nativescript-cli/actions/workflows/npm_release_cli.yml/badge.svg)](https://github.com/NativeScript/nativescript-cli/actions/workflows/npm_release_cli.yml)\n\nGet it using: `npm install -g nativescript`\n\n- [What is NativeScript](#what-is-nativescript)\n- [How the NativeScript CLI works](#how-the-nativescript-cli-works)\n- [Supported Platforms](#supported-platforms)\n- [System Requirements](#system-requirements)\n- [Installation](#installation)\n  - [Install the NativeScript CLI](#install-the-nativescript-cli)\n  - [Configure Proxy Settings](#configure-proxy-settings)\n    - [Set Proxy Settings](#set-proxy-settings)\n      - [Attributes](#attributes)\n      - [Options](#options)\n      - [Limitations](#limitations)\n    - [Display Current Proxy Settings](#display-current-proxy-settings)\n    - [Clear Proxy Settings](#clear-proxy-settings)\n- [Quick Start](#quick-start)\n  - [The Commands](#the-commands)\n  - [Create Project](#create-project)\n  - [Develop Your Project](#develop-your-project)\n    - [Development with NativeScript](#development-with-nativescript)\n    - [Development in `app`](#development-in-app)\n    - [Development in `platforms`](#development-in-platforms)\n    - [Modifying Configuration Files](#modifying-configuration-files)\n    - [Modifying Entitlements File (iOS only)](#modifying-entitlements-file-ios-only)\n  - [Build Your Project](#build-your-project)\n  - [Run Your Project](#run-your-project)\n- [Extending the CLI](#extending-the-cli)\n- [Troubleshooting](#troubleshooting)\n- [How to Contribute](#how-to-contribute)\n- [How to Build](#how-to-build)\n- [Get Help](#get-help)\n- [License](#license)\n\nWhat is NativeScript\n===\n\nNativeScript provides platform APIs directly to the JavaScript runtime (_with strong types_) for a rich TypeScript development experience. \n\nSome popular use cases:\n\n- Building Web, iOS, Android and Vision Pro apps with a shared codebase (aka, cross platform apps)\n- Building native platform apps with portable JavaScript skills\n- Augmenting JavaScript projects with platform API capabilities\n- AndroidTV and Watch development\n- watchOS development\n- Learning native platforms through JavaScript understanding\n- Exploring platform API documentation by trying APIs [directly from a web browser](https://preview.nativescript.org/) without requiring a platform development machine setup.\n\nTo learn more about NativeScript, you can check the following resources:\n\n* [The NativeScript web page][2]\n* [NativeScript - a Technical Overview][7]\n* [Announcing NativeScript - cross-platform framework for building native mobile applications][8]\n* The NativeScript [Documentation repo][3] and [Documentation portal][4]\n* [The NativeScript FAQ][6]\n\n[Back to Top][1]\n\nHow the NativeScript CLI works\n===\n\nThe NativeScript CLI is the command-line interface for interacting with NativeScript. It incorporates several important services. Consider the following diagram:\n\n![NativeScript CLI diagram](https://github.com/NativeScript/nativescript-cli/raw/release/ns-cli.png)\n\n* **Commands** - pretty much what every CLI does - support of different command options, input validation and help  \n* **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\n* **LiveSync Service** - redeploys applications when code changes during development\n* **Hooks Service** - executes custom-written hooks in developed application, thus modifying the build process\n* **Platforms Service** - provides app build functionalities, uses Gradle to build Android packages and Xcode for iOS. \n\n[Back to Top][1]\n\nSupported Platforms\n===\n\nWith the NativeScript CLI, you can target the following mobile platforms.\n\n* Android 4.2 or a later stable official release\n* iOS 9.0 or later stable official release\n\n[Back to Top][1]\n\nSystem Requirements\n===\n\nYou can install and run the NativeScript CLI on Windows, macOS or Linux.\n\n* [Windows](https://docs.nativescript.org/start/ns-setup-win)\n* [macOS](https://docs.nativescript.org/start/ns-setup-os-x)\n* [Linux](https://docs.nativescript.org/start/ns-setup-linux)\n\nInstallation\n===\n\n## Install the NativeScript CLI\n\nThe NativeScript CLI is available for installing as an npm package.\n\nIn the command prompt, run the following command.\n\nOS | Node.js installed from https://nodejs.org/ | Node.js installed via package manager\n---|---------------------|----\nWindows | `npm install nativescript -g` | `npm install nativescript -g`\nmacOS | `sudo npm install nativescript -g --unsafe-perm` | `npm install nativescript -g`\nLinux | `sudo npm install nativescript -g --unsafe-perm` | `npm install nativescript -g`\n\nTo check if your system is configured properly, run the following command.\n\n```Shell\nns doctor\n```\n\n## Configure Proxy Settings\n\nIf you are working with the NativeScript CLI behind a web proxy, you need to configure your proxy settings.\n\n### Set Proxy Settings\n\n```Shell\nns proxy set \u003cUrl\u003e \u003cUsername\u003e \u003cPassword\u003e\n```\n\n#### Attributes\n\n\u003cdetails\u003e\u003csummary\u003e\u003ccode\u003e\u0026lt;Url\u0026gt;\u003c/code\u003e\u003c/summary\u003e\n\u003cstrong\u003e(Required)\u003c/strong\u003e The full URL of the proxy. The \u003ccode\u003e\u0026lt;Url\u0026gt;\u003c/code\u003e 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 \u003ccode\u003ehttp://127.0.0.1:8888\u003c/code\u003e.\u003c/details\u003e\n \n\u003cdetails\u003e\u003csummary\u003e\u003ccode\u003e\u0026lt;Username\u0026gt;\u003c/code\u003e and \u003ccode\u003e\u0026lt;Password\u0026gt;\u003c/code\u003e\u003c/summary\u003e\n\u003cstrong\u003e(Optional)\u003c/strong\u003e The credentials for the proxy. The \u003ccode\u003e\u0026lt;Username\u0026gt;\u003c/code\u003e and \u003ccode\u003e\u0026lt;Password\u0026gt;\u003c/code\u003e attributes are optional, however, if you choose to provide them, you must provide both.\u003c/details\u003e \n\n#### Options\n\n\u003cdetails\u003e\u003csummary\u003e\u003ccode\u003e--insecure\u003c/code\u003e\u003c/summary\u003e\nThe \u003ccode\u003e--insecure\u003c/code\u003e flag 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.\u003c/details\u003e\n\n#### Limitations\n\n* You can provide the `\u003cUsername\u003e` and `\u003cPassword\u003e` attributes only on Windows systems.\n* Proxy settings for the npm, the Android Gradle and (optional) Docker need to be configured separately. For more information, see the following articles:\n\t* [Configure the npm proxy](https://docs.npmjs.com/misc/config#https-proxy)\n\t* [Configure the Android Gradle proxy](https://docs.gradle.org/3.3/userguide/build_environment.html#sec:accessing_the_web_via_a_proxy)\n    * [Configure the Docker proxy](https://docs.docker.com/network/proxy/)\n\n### Display Current Proxy Settings\n\n```Shell\nns proxy\n```\n\n### Clear Proxy Settings\n\n```Shell\nns proxy clear\n```\n\n[Back to Top][1]\n\nQuick Start\n===\n\n* [The Commands](#the-commands)\n* [Create Project](#create-project)\n* [Develop Your Project](#develop-your-project)\n* [Build Your Project](#build-your-project)\n* [Run Your Project](#run-your-project)\n\n## The Commands\n\nRun `ns help` to view all available commands in the browser. Run `ns help \u003cCommand\u003e` to view more information about a selected command in the browser. `ns --help` opens console help, where help information is shown in the console.\n\n[Back to Top][1]\n\n## Create Project\n\nTo create a new cross-platform project from the default JavaScript template, run the following command.\n\n```Shell\nns create MyApp --js\n```\n\nTo create a new cross-platform project from the default TypeScript, Angular or Vue template, use the `template` option followed by either `typescript`, `angular` or `vue`.\n\n```Shell\nns create MyApp --template typescript\nns create MyApp --template angular\nns create MyApp --template vue\n```\n\nOr you can simply use the shorthand `tsc` and `ng` options.\n\n```Shell\nns create MyApp --tsc\nns create MyApp --ng\n```\nWith the `template` option you can also specify a local or a remote path to the template that you want to use to create your project.\nFor example, if you want to create a React template, run the following command.\n\n```Shell\nns create MyApp --template https://github.com/shirakaba/tns-template-blank-react.git\n```\n\nThe NativeScript CLI creates a new project and sets the application identifier to `org.nativescript.myapp`.\n\nThe CLI places the project in a new directory in the current directory. The newly created directory has the following structure.\n\n```\nMyApp/\n├── app\n│   ├── App_Resources\n│   └── ...\n└── platforms\n    └── ...\n```\n\n* The `app` directory is the **development space for your application**. You should modify all common and platform-specific code within this directory. When you run `prepare \u003cPlatform\u003e`, the NativeScript CLI prepares relevant content to the platform-specific folders for each target platform.\n* The `platforms` directory 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 \u003cPlatform\u003e`, the NativeScript CLI prepares relevant content from the `app` directory to the platform-specific subdirectory for each target platform.\n\n[Back to Top][1]\n\n## Develop Your Project\n\n* [Development with NativeScript](#development-with-nativescript)\n* [Development in app](#development-in-app)\n* [Development in platforms](#development-in-platforms)\n\n### Development with NativeScript\n\nFor more information about working with NativeScript, see the following resources.\n\n* [The NativeScript Documentation Wiki][3]\n* [The NativeScript API Reference][5]\n\n### Development in `app`\n\nThe `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.**\n\nIn the `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.ios.extension` or `name.android.extension`. For example: `main.ios.js` or `main.android.js`.\n\nYou 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 `.android.` or `.ios.` string.\n\n### Development in `platforms`\n\n\u003e **IMPORTANT:** Avoid editing files located in the `platforms` subdirectory because the NativeScript CLI overrides such files.\n\n### Modifying Configuration Files\n\nThe NativeScript CLI respects any platform configuration files placed inside `app/App_Resources`.\n\n### Modifying Entitlements File (iOS only)\n\nTo specify which capabilities are required by your App - Maps, Push Notifications, Wallet 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/\u003capplication name\u003e/\u003capplication name\u003e.entitlements` and will be linked in the `build.xcconfig` file.\n\nYou can always override the generated entitlements file, by pointing to your own entitlements file by setting the `CODE_SIGN_ENTITLEMENTS` property in the `app/App_Resources/iOS/build.xcconfig` file.\n\n[Back to Top][1]\n\n## Build Your Project\n\nYou can build it for your target mobile platforms.\n\n```Shell\nns build android\nns build ios\n```\n\nThe NativeScript CLI calls the SDK for the selected target platform and uses it to build your app locally.\n\nWhen 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 `--emulator` flag.\n\n\u003e **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](https://seventhsoulmountain.blogspot.com/2013/09/ios-code-sign-in-complete-walkthrough.html).\n\n[Back to Top][1]\n\n## Run Your Project\n\nYou can test your work in progress on connected Android or iOS devices.\n\nTo verify that the NativeScript CLI recognizes your connected devices, run the following command.\n\n```Shell\nns devices\n```\n\nThe NativeScript CLI lists all connected physical devices and running emulators/simulators.\n\nAfter you have listed the available devices, you can quickly run your app on connected devices by executing:\n\n```Shell\nns run android\nns run ios\n```\n\n[Back to Top][1]\n\nExtending the CLI\n===\n\nThe NativeScript CLI lets you extend its behavior and customize it to fit your needs by using [hooks](https://en.wikipedia.org/wiki/Hooking).\n\nWhen you run one of the extendable commands (for example, `ns build`), the CLI checks for hooks and executes them. Plugins can also use hooks to control the compilation of the application package.\n\nFor more information, see the [Extending the CLI document](https://github.com/NativeScript/nativescript-cli/blob/master/extending-cli.md)\n\n[Back to Top][1]\n\nTroubleshooting\n===\n\nIf 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.\n\n```bash\nns doctor\n```\n\nThis command prints warnings about current configuration issues and provides basic information about how to resolve them.\n\nIf addressing the configuration issues does not resolve your problem, you can [report an issue](https://github.com/NativeScript/nativescript-cli/blob/master/CONTRIBUTING.md#report-an-issue) or [ask the community](https://stackoverflow.com/questions/tagged/nativescript).\n\n[Back to Top][1]\n\nHow to Contribute\n===\n\nTo learn how to log a bug that you just discovered, click [here](https://github.com/NativeScript/nativescript-cli/blob/master/CONTRIBUTING.md#report-an-issue).\n\nTo learn how to suggest a new feature or improvement, click [here](https://github.com/NativeScript/nativescript-cli/blob/master/CONTRIBUTING.md#request-a-feature).\n\nTo learn how to contribute to the code base, click [here](https://github.com/NativeScript/nativescript-cli/blob/master/CONTRIBUTING.md#contribute-to-the-code-base).\n\n[Back to Top][1]\n\nHow to Build\n===\n```\ngit clone https://github.com/NativeScript/nativescript-cli\ncd nativescript-cli\nnpm run setup\n```\n\nTo use the locally built CLI instead of `ns` you can call `PATH_TO_CLI_FOLDER/bin/ns`. For example:\n`PATH_TO_CLI_FOLDER/bin/ns run ios|android`\n\n[Back to Top][1]\n\nGet Help\n===\n\nPlease, use [github issues](https://github.com/NativeScript/nativescript-cli/issues) strictly for [reporting bugs](CONTRIBUTING.md#report-an-issue) or [requesting features](CONTRIBUTING.md#request-a-feature). For general NativeScript questions and support, check out [Stack Overflow](https://stackoverflow.com/questions/tagged/nativescript) or ask our experts in the [NativeScript community Discord channel](https://nativescript.org/discord).\n\n[Back to Top][1]\n\nLicense\n===\n\nThis software is licensed under the Apache 2.0 license, quoted \u003ca href=\"LICENSE\" target=\"_blank\"\u003ehere\u003c/a\u003e.\n\n[Back to Top][1]\n\n[1]: #nativescript-command-line-interface\n[2]: https://nativescript.org\n[3]: https://github.com/nativescript/docs\n[4]: https://docs.nativescript.org/\n[5]: https://docs.nativescript.org/api-reference\n[6]: https://www.nativescript.org/faq\n[7]: https://docs.nativescript.org/core-concepts/technical-overview\n[8]: https://www.telerik.com/blogs/announcing-nativescript---cross-platform-framework-for-building-native-mobile-applications\n","funding_links":["https://github.com/sponsors/NativeScript","https://opencollective.com/nativescript"],"categories":["JavaScript","cli"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNativeScript%2Fnativescript-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNativeScript%2Fnativescript-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNativeScript%2Fnativescript-cli/lists"}