The Command-Line Interface

This guide shows you how to create applications and deploy them tovarious native mobile platforms using the cordova command-lineinterface (CLI). This tool allows you to create new projects, buildthem on different platforms, and run on real devices or withinemulators. The CLI is the main tool to use for the cross-platformworkflow described in the Overview. Otherwise you can also use theCLI to initialize project code, then switch to various platforms' SDKsand shell tools for continued development.

Prerequisites

Before running any command-line tools, you need to install SDKs foreach platform you wish to target.(See the Platform Guides for more details.)

To add support or rebuild a project for any platform, you need to runthe command-line interface from the same machine that supports theplatform'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 7 (Windows)
• Windows Phone 8 (Windows)
• Windows 8 (Windows)
• Firefox OS (Mac, Linux, Windows)

On the Mac, the command-line is available via the Terminalapplication. On the PC, it's available as Command Prompt underAccessories.

NOTE: For Windows-only platforms, you can still do yourdevelopment on Mac hardware by running Windows in a virtual machineenvironment or in dual-boot mode. For available options, see theWindows Phone Platform Guide or the Windows 8 Platform Guide.

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 aready-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. Followinginstallation, you should be able to invoke node and npm on yourcommand line. If desired, you may optionally use a tool such as nvm or nave to manage your Node.js installation.

2. Download and install a git client, if you don'talready have one. Following installation, you should be able to invoke giton your command line. Even though you won't be using git manually,the CLI does use it behind-the-scenes to download some assets whencreating a new project.

3. Install the cordova module using npm utility of Node.js. The cordovamodule 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 withsudo may be necessary to install this development utility inotherwise restricted directories such as /usr/local/share. If you are using the optionalnvm/nave tool or have write access to the install directory,you may be able to omit the sudo prefix. There aremore tipsavailable 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. Otherwiseit will be installed in the node_modules subdirectory of the currentworking directory.

   You may need to add the npm directory to your PATH in order to invokeglobally installed npm modules. On Windows, npm can usually be found atC:\Users\username\AppData\Roaming\npm. On OS X and Linux it can usuallybe found at /usr/local/share/npm.

   The installation log may produce errors for any uninstalledplatform SDKs.

   Following installation, you should be able to runcordova on the command line with no arguments and it shouldprint help text.

Create the App

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

    $ cordova create hello com.example.hello HelloWorld

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

The first argument hello specifies a directory to be generatedfor your project. This directory should not already exist, Cordova willcreate it for you. Its www subdirectory houses your application'shome page, along with various resources under css, js, and img,which follow common web development file-naming conventions. Theconfig.xml file contains important metadata needed to generate anddistribute the application.

The second argument com.example.helloprovides your project with a reverse domain-style identifier. This argumentis optional, but only if you also omit the third argument, since the argumentsare positional. You can editthis value later in the config.xml file, but do be aware that there maybe code generated outside of config.xml using this value, such as Javapackage names. The default value is io.cordova.hellocordova, but it isrecommended 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.xmlfile, but do be aware that there may be code generated outside of config.xmlusing 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,or any subdirectories within its scope:

    $ cd hello

Before you can build the project, you need to specify a set of targetplatforms. Your ability to run these commands depends on whether yourmachine supports each SDK, and whether you have already installed eachSDK. Run any of these from a Mac:

    $ cordova platform add ios
    $ cordova platform add amazon-fireos
    $ cordova platform add android
    $ cordova platform add blackberry10
    $ cordova platform add firefoxos

Run any of these from a Windows machine, where wp refers todifferent versions of the Windows Phone operating system:

    $ cordova platform add wp7
    $ cordova platform add wp8
    $ cordova platform add windows8
    $ cordova platform add amazon-fireos
    $ cordova platform add android
    $ cordova platform add blackberry10
    $ cordova platform add firefoxos

Run this to check your current set of platforms:

    $ cordova platforms ls

(Note the platform and platforms commands are synonymous.)

Run either of the following synonymous commands to remove a platform:

    $ cordova platform remove blackberry10
    $ cordova platform rm amazon-fireos
    $ cordova platform rm android

Running commands to add or remove platforms affects the contents ofthe project's platforms directory, where each specified platformappears as a subdirectory. The www source directory is reproducedwithin each platform's subdirectory, appearing for example inplatforms/ios/www or platforms/android/assets/www. Because the CLIconstantly copies over files from the source www folder, you should onlyedit these files and not the ones located under the platforms subdirectories.If you use version control software, you should add this source www folder, along with the merges folder, to your version control system. (More informationabout the merges folder can be found in the Customize Each Platform section below.)

WARNING: When using the CLI to build your application, you shouldnot edit any files in the /platforms/ directory unless you knowwhat you are doing, or if documentation specifies otherwise. The filesin this directory are routinely overwritten when preparingapplications for building, or when plugins are reinstalled.

If you wish at this point, you can use an SDK such as Eclipse or Xcodeto open the project you created. You will need to open the derivative set of assetsfrom the /platforms/ directory to develop with an SDK. This is becausethe SDK specific metadata files are stored within the appropriate /platform/ subdirectory.(See the Platform Guides for information on how to develop applications within each IDE.)Use this approach if you simply want to initialize a project using the CLI and then switch to an SDK for native work.

Read on if you wish to use the cross-platform workflow approach (the CLI) for the entiredevelopment cycle.

Build the App

By default, the cordova create script generates a skeletal web-basedapplication whose home page is the project's www/index.html file.Edit this application however you want, but any initialization shouldbe specified as part of the deviceready event handler, referenced bydefault from www/js/index.js.

Run the following command to iteratively build the project:

    $ cordova build

This generates platform-specific code within the project's platformssubdirectory. You can optionally limit the scope of each build tospecific platforms:

    $ cordova build ios

The cordova build command is a shorthand for the following, which inthis example is also targeted to a single platform:

    $ cordova prepare ios
    $ cordova compile ios

In this case, once you run prepare, you can use Apple's Xcode SDK asan alternative to modify and compile the platform-specific code thatCordova generates within platforms/ios. You can use the sameapproach with other platforms' SDKs.

Test the App on an Emulator or Device

SDKs for mobile platforms often come bundled with emulators thatexecute a device image, so that you can launch the app from the homescreen and see how it interacts with many platform features. Run acommand such as the following to rebuild the app and view it within aspecific platform's emulator:

    $ cordova emulate android

Some mobile platforms emulate a particular device by default, such asthe iPhone for iOS projects. For other platforms, you may need tofirst associate a device with an emulator.

NOTE: Emulator support is currently not available for Amazon Fire OS.

(See the Platform Guides for details.)For example, you may first run the android command to launch theAndroid SDK, then run a particular device image, which launches itaccording to its default behavior:

Following up with the cordova emulate command refreshes the emulatorimage to display the latest application, which is now available forlaunch from the home screen:

Alternately, you can plug the handset into your computer and test theapp directly:

    $ cordova run android

Before running this command, you need to set up the device fortesting, following procedures that vary for each platform. InAndroid and Amazon Fire OS devices, you would have to enable a USB debugging option onthe device, and perhaps add a USB driver depending on your developmentenvironmnent.See Platform Guides for details on each platform's requirements.

Add Plugin Features

When you build and view a new project, the default application thatappears doesn't do very much. You can modify the app in many ways totake advantage of standard web technologies, but for the app tocommunicate closely with various device-level features, you need toadd plugins that provide access to core Cordova APIs.

A plugin is a bit of add-on code that provides an interface tonative components. You can design your own plugin interface, forexample when designing a hybrid app that mixes a Cordova WebView withnative components. (See Embedding WebViews and Plugin DevelopmentGuide for details.) More commonly, you would add a plugin to enableone of Cordova's basic device-level featuresdetailed in the API Reference. A list of these plugins, includingadditional third-party plugins provided by the community, can be foundin the registry atplugins.cordova.io. You can usethe CLI to search for plugins from this registry. For example,searching for bar and code produces a single result that matchesboth terms as case-insensitive substrings:

    $ cordova plugin search bar code

    com.phonegap.plugins.barcodescanner - Scans Barcodes

Searching for only the bar term yields and additional result:

    org.apache.cordova.statusbar - Cordova StatusBar Plugin

The cordova plugin add command requires you to specify therepository for the plugin code. Here are examples of how you mightuse the CLI to add features to the app:

• Basic device information (Device API):

  $ cordova plugin add org.apache.cordova.device
  

• Network Connection and Battery Events:

  $ cordova plugin add org.apache.cordova.network-information
  $ cordova plugin add org.apache.cordova.battery-status
  

• Accelerometer, Compass, and Geolocation:

  $ cordova plugin add org.apache.cordova.device-motion
  $ cordova plugin add org.apache.cordova.device-orientation
  $ cordova plugin add org.apache.cordova.geolocation
  

• Camera, Media playback and Capture:

  $ cordova plugin add org.apache.cordova.camera
  $ cordova plugin add org.apache.cordova.media-capture
  $ cordova plugin add org.apache.cordova.media
  

• Access files on device or network (File API):

  $ cordova plugin add org.apache.cordova.file
  $ cordova plugin add org.apache.cordova.file-transfer
  

• Notification via dialog box or vibration:

  $ cordova plugin add org.apache.cordova.dialogs
  $ cordova plugin add org.apache.cordova.vibration
  

• Contacts:

  $ cordova plugin add org.apache.cordova.contacts
  

• Globalization:

  $ cordova plugin add org.apache.cordova.globalization
  

• Splashscreen:

  $ cordova plugin add org.apache.cordova.splashscreen
  

• Open new browser windows (InAppBrowser):

  $ cordova plugin add org.apache.cordova.inappbrowser
  

• Debug console:

  $ cordova plugin add org.apache.cordova.console
  

NOTE: The CLI adds plugin code as appropriate for each platform.If you want to develop with lower-level shell tools or platform SDKsas discussed in the Overview, you need to run the Plugman utility toadd plugins separately for each platform. (For more information, seeUsing Plugman to Manage Plugins.)

Use plugin ls (or plugin list, or plugin by itself) to viewcurrently installed plugins. Each displays by its identifier:

    $ cordova plugin ls    # or 'plugin list'
    [ 'org.apache.cordova.console' ]

To remove a plugin, refer to it by the same identifier that appears inthe listing. For example, here is how you would remove support for adebug console from a release version:

    $ cordova plugin rm org.apache.cordova.console
    $ cordova plugin remove org.apache.cordova.console    # same

You can batch-remove or add plugins by specifying more than oneargument for each command:

    $ cordova plugin add org.apache.cordova.console org.apache.cordova.device

Advanced Plugin Options

When adding a plugin, several options allow you to specify from whereto fetch the plugin. The examples above use a well-knownregistry.phonegap.com registry, and the plugin is specified by theid:

    $ cordova plugin add org.apache.cordova.console

The id may also include the plugin's version number, appended afteran @ character. The latest version is an alias for the most recentversion. For example:

    $ cordova plugin add org.apache.cordova.console@latest
    $ cordova plugin add org.apache.cordova.console@0.2.1

If the plugin is not registered at registry.phonegap.com but is located inanother git repository, you can specify an alternate URL:

    $ cordova plugin add https://github.com/apache/cordova-plugin-console.git

The git example above fetches the plugin from the end of the masterbranch, but an alternate git-ref such as a tag or branch can beappended after a # character:

    $ cordova plugin add https://github.com/apache/cordova-plugin-console.git#r0.2.0

If the plugin (and its plugin.xml file) is in a subdirectory withinthe git repo, you can specify it with a : character. Note that the# character is still needed:

    $ cordova plugin add https://github.com/someone/aplugin.git#:/my/sub/dir

You can also combine both the git-ref and the subdirectory:

    $ cordova plugin add https://github.com/someone/aplugin.git#r0.0.1:/my/sub/dir

Alternately, specify a local path to the plugin directory thatcontains the plugin.xml file:

    $ cordova plugin add ../my_plugin_dir

Using merges to Customize Each Platform

While Cordova allows you to easily deploy an app for many differentplatforms, sometimes you need to add customizations. In that case,you don't want to modify the source files in various www directorieswithin the top-level platforms directory, because they're regularlyreplaced with the top-level www directory's cross-platform source.

Instead, the top-level merges directory offers a place to specifyassets to deploy on specific platforms. Each platform-specificsubdirectory within merges mirrors the directory structure of thewww source tree, allowing you to override or add files as needed.For example, here is how you might uses merges to boost the defaultfont size for Android and Amazon Fire OS devices:

• Edit the www/index.html file, adding a link to an additional CSSfile, overrides.css in this case:

   rel="stylesheet" type="text/css" href="css/overrides.css" />
  

• Optionally create an empty www/css/overrides.css file, which wouldapply for all non-Android builds, preventing a missing-file error.

• Create a css subdirectory within merges/android, then add acorresponding overrides.css file. Specify CSS that overrides the12-point default font size specified within www/css/index.css, forexample:

  body { font-size:14px; }
  

When you rebuild the project, the Android version features the customfont size, while others remain unchanged.

You can also use merges to add files not present in the originalwww directory. For example, an app can incorporate a back buttongraphic into the iOS interface, stored inmerges/ios/img/back_button.png, while the Android version caninstead capture backbutton events from the corresponding hardwarebutton.

Help Commands

Cordova features a couple of global commands, which may help you ifyou get stuck or experience a problem. The help command displaysall available Cordova commands and their syntax:

$ cordova help
$ cordova        # same

The info command produces a listing of potentially useful details,such as currently installed platforms and plugins, SDK versions foreach platform, and versions of the CLI and node.js:

$ cordova info

It both presents the information to screen and captures the output ina local info.txt file.

NOTE: Currently, only details on iOS and Android platforms areavailable.

Updating Cordova and Your Project

After installing the cordova utility, you can always update it tothe latest version by running the following command:

    $ sudo npm update -g cordova

Use this syntax to install a specific version:

    $ sudo npm install -g cordova@3.1.0-0.2.0

Run cordova -v to see which version is currently running. Run the npminfo command for a longer listing that includes the current versionalong with other available version numbers:

    $ npm info cordova

Cordova 3.0 is the first version to support the command-line interfacedescribed in this section. If you are updating from a version prior to3.0, you need to create a new project as described above, then copythe older application's assets into the top-level www directory.Where applicable, further details about upgrading to 3.0 are availablein the Platform Guides. Once you upgrade to the cordovacommand-line interface and use npm update to stay current, the moretime-consuming procedures described there are no longer relevant.

Cordova 3.0+ may still require various changes toproject-level directory structures and other dependencies. After yourun the npm command above to update Cordova itself, you may need toensure your project's resources conform to the latest version'srequirements. Run a command such as the following for each platformyou're building:

    $ cordova platform update android
    $ cordova platform update ios
    ...etc.