<commit_before>---
license: >
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.

title: The Command-Line Interface
---

# The Command-Line Interface

This guide shows you how to create applications and deploy them to
various native mobile platforms using the `cordova` command-line
interface (CLI). This tool allows you to create new projects, build
them on different platforms, and run on real devices or within
emulators. The CLI is the main tool to use for the cross-platform
workflow described in the [Overview](../overview/index.html).  Otherwise you can also use the
CLI to initialize project code, then switch to various platforms' SDKs
and shell tools for continued development.

## Prerequisites

Before running any command-line tools, you need to install SDKs for
each platform you wish to target.
(See the [Platform Guides](../platforms/index.html) for more details.)

To add support or rebuild a project for any platform, you need to run
the command-line interface from the same machine that supports the
platform's SDK. The CLI supports the following combinations:

* iOS             (Mac)
* Amazon Fire OS  (Mac, Linux, Windows)
* Android         (Mac, Linux, Windows)
* BlackBerry 10   (Mac, Linux, Windows)
* Windows Phone 8 (Windows)
* Windows         (Windows)
* Firefox OS      (Mac, Linux, Windows)

On the Mac, the command-line is available via the _Terminal_
application. On the PC, it's available as _Command Prompt_ under
_Accessories_.

__NOTE__: For Windows-only platforms, you can still do your
development on Mac hardware by running Windows in a virtual machine
environment or in dual-boot mode. For available options, see the
[Windows Phone 8 Platform Guide](../platforms/wp8/index.html) or the [Windows Platform Guide](../platforms/win8/index.html).

The more likely it is that you run the CLI from different machines,
the more it makes sense to maintain a remote source code repository,
whose assets you pull down to local working directories.

## Installing the Cordova CLI

The Cordova command-line tool is distributed as an npm package in a
ready-to-use format. It is not necessary to compile it from source.

To install the `cordova` command-line tool, follow these steps:

1. Download and install [Node.js](http://nodejs.org/). Following
   installation, you should be able to invoke `node` and `npm` on your
   command line. If desired, you may optionally use a tool such as `nvm` 
   or `nave` to manage your Node.js installation.

1. Download and install a [git client](http://git-scm.com/), if you don't
   already have one. Following installation, you should be able to invoke `git`
   on your command line. Even though you won't be using `git` manually,
   the CLI does use it behind-the-scenes to download some assets when
   creating a new project.

1. Install the `cordova` module using `npm` utility of Node.js. The `cordova`
   module will automatically be downloaded by the `npm` utility.

   * on OS X and Linux:

            $ sudo npm install -g cordova

       On OS X and Linux, prefixing the `npm` command with
       `sudo` may be necessary to install this development utility in
       otherwise restricted directories such as 
       `/usr/local/share`. If you are using the optional
       nvm/nave tool or have write access to the install directory,
       you may be able to omit the `sudo` prefix. There are
       [more tips](http://justjs.com/posts/npm-link-developing-your-own-npm-modules-without-tears)
       available on using `npm` without `sudo`, if you desire to do that.

   * on Windows:

            C:\>npm install -g cordova

   The `-g` flag above tells `npm` to install `cordova` globally. Otherwise
   it will be installed in the `node_modules` subdirectory of the current
   working directory.

   You may need to add the `npm` directory to your `PATH` in order to invoke
   globally installed `npm` modules. On Windows, `npm` can usually be found at
   `C:\Users\username\AppData\Roaming\npm`. On OS X and Linux it can usually
   be found at `/usr/local/share/npm`.
   
   The installation log may produce errors for any uninstalled
   platform SDKs.

   Following installation, you should be able to run
   `cordova` on the command line with no arguments and it should
   print help text.

## Create the App

Go to the directory where you maintain your source code, and run a
command such as the following:

        $ cordova create hello com.example.hello HelloWorld

It may take some time for the command to complete, so be patient. Running
the command with the ` -d` option displays information about its progress.

The first argument _hello_ specifies a directory to be generated
for your project. This directory should not already exist, Cordova will
create it for you. Its `www` subdirectory houses your application's
home page, along with various resources under `css`, `js`, and `img`,
which follow common web development file-naming conventions. These assets
will be stored on the device's local filesystem, not served remotely. The
`config.xml` file contains important metadata needed to generate and
distribute the application.

The second argument `com.example.hello`
provides your project with a reverse domain-style identifier. This argument
is optional, but only if you also omit the third argument, since the arguments
are positional. You can edit
this value later in the `config.xml` file, but do be aware that there may
be code generated outside of `config.xml` using this value, such as Java
package names. The default value is `io.cordova.hellocordova`, but it is
recommended that you select an appropriate value.

The third argument `HelloWorld` provides the application's display title.
This argument is optional. You can edit this value later in the `config.xml`
file, but do be aware that there may be code generated outside of `config.xml`
using this value, such as Java class names. The default value is `HelloCordova`,
but it is recommended that you select an appropriate value.

## Add Platforms

All subsequent commands need to be run within the project's directory,<commit_msg>CB-9964 - Add --template to online documentation<commit_after>---
license: >
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.

title: The Command-Line Interface
---

# The Command-Line Interface

This guide shows you how to create applications and deploy them to
various native mobile platforms using the `cordova` command-line
interface (CLI). This tool allows you to create new projects, build
them on different platforms, and run on real devices or within
emulators. The CLI is the main tool to use for the cross-platform
workflow described in the [Overview](../overview/index.html).  Otherwise you can also use the
CLI to initialize project code, then switch to various platforms' SDKs
and shell tools for continued development.

## Prerequisites

Before running any command-line tools, you need to install SDKs for
each platform you wish to target.
(See the [Platform Guides](../platforms/index.html) for more details.)

To add support or rebuild a project for any platform, you need to run
the command-line interface from the same machine that supports the
platform's SDK. The CLI supports the following combinations:

* iOS             (Mac)
* Amazon Fire OS  (Mac, Linux, Windows)
* Android         (Mac, Linux, Windows)
* BlackBerry 10   (Mac, Linux, Windows)
* Windows Phone 8 (Windows)
* Windows         (Windows)
* Firefox OS      (Mac, Linux, Windows)

On the Mac, the command-line is available via the _Terminal_
application. On the PC, it's available as _Command Prompt_ under
_Accessories_.

__NOTE__: For Windows-only platforms, you can still do your
development on Mac hardware by running Windows in a virtual machine
environment or in dual-boot mode. For available options, see the
[Windows Phone 8 Platform Guide](../platforms/wp8/index.html) or the [Windows Platform Guide](../platforms/win8/index.html).

The more likely it is that you run the CLI from different machines,
the more it makes sense to maintain a remote source code repository,
whose assets you pull down to local working directories.

## Installing the Cordova CLI

The Cordova command-line tool is distributed as an npm package in a
ready-to-use format. It is not necessary to compile it from source.

To install the `cordova` command-line tool, follow these steps:

1. Download and install [Node.js](http://nodejs.org/). Following
   installation, you should be able to invoke `node` and `npm` on your
   command line. If desired, you may optionally use a tool such as `nvm` 
   or `nave` to manage your Node.js installation.

1. Download and install a [git client](http://git-scm.com/), if you don't
   already have one. Following installation, you should be able to invoke `git`
   on your command line. Even though you won't be using `git` manually,
   the CLI does use it behind-the-scenes to download some assets when
   creating a new project.

1. Install the `cordova` module using `npm` utility of Node.js. The `cordova`
   module will automatically be downloaded by the `npm` utility.

   * on OS X and Linux:

            $ sudo npm install -g cordova

       On OS X and Linux, prefixing the `npm` command with
       `sudo` may be necessary to install this development utility in
       otherwise restricted directories such as 
       `/usr/local/share`. If you are using the optional
       nvm/nave tool or have write access to the install directory,
       you may be able to omit the `sudo` prefix. There are
       [more tips](http://justjs.com/posts/npm-link-developing-your-own-npm-modules-without-tears)
       available on using `npm` without `sudo`, if you desire to do that.

   * on Windows:

            C:\>npm install -g cordova

   The `-g` flag above tells `npm` to install `cordova` globally. Otherwise
   it will be installed in the `node_modules` subdirectory of the current
   working directory.

   You may need to add the `npm` directory to your `PATH` in order to invoke
   globally installed `npm` modules. On Windows, `npm` can usually be found at
   `C:\Users\username\AppData\Roaming\npm`. On OS X and Linux it can usually
   be found at `/usr/local/share/npm`.
   
   The installation log may produce errors for any uninstalled
   platform SDKs.

   Following installation, you should be able to run
   `cordova` on the command line with no arguments and it should
   print help text.

## Create the App

Go to the directory where you maintain your source code, and run a
command such as the following:

        $ cordova create hello com.example.hello HelloWorld [--template templatePath]

It may take some time for the command to complete, so be patient. Running
the command with the ` -d` option displays information about its progress.

The first argument _hello_ specifies a directory to be generated
for your project. This directory should not already exist, Cordova will
create it for you. Its `www` subdirectory houses your application's
home page, along with various resources under `css`, `js`, and `img`,
which follow common web development file-naming conventions. These assets
will be stored on the device's local filesystem, not served remotely. The
`config.xml` file contains important metadata needed to generate and
distribute the application.

The second argument `com.example.hello`
provides your project with a reverse domain-style identifier. This argument
is optional, but only if you also omit the third argument, since the arguments
are positional. You can edit
this value later in the `config.xml` file, but do be aware that there may
be code generated outside of `config.xml` using this value, such as Java
package names. The default value is `io.cordova.hellocordova`, but it is
recommended that you select an appropriate value.

The third argument `HelloWorld` provides the application's display title.
This argument is optional. You can edit this value later in the `config.xml`
file, but do be aware that there may be code generated outside of `config.xml`
using this value, such as Java class names. The default value is `HelloCordova`,
but it is recommended that you select an appropriate value.

The fourth argument `--template templatePath` allows for a template application
to be used to create a project. All files, and folders from the template will
be copied into the new project. Platforms, and plugins may be included in a
template, but are optional. This argument is optional. The path to the
template can be a local path, NPM module, or Git URL.

## Add Platforms

All subsequent commands need to be run within the project's directory,
{'fraction_non_alphanumeric': 0.058627770303759826, 'fraction_numerical': 0.002124194576223182, 'mean_word_length': 3.7064311896034656, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 10}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4804745', 'n_tokens_mistral': 3674, 'n_tokens_neox': 3514, 'n_words': 2030}