Blog

All the latest news and insights on PhoneGap

PhoneGap CLI 3.6.3

The PhoneGap CLI has received a big update! It’s now aligned more closely with Cordova and supports all of Cordova’s features and commands. It also resolves a large number of inconsistencies and issues that emerged over the past year.

As always, you can install the PhoneGap CLI with:

# OS X / Linux
$ sudo npm install -g phonegap
# Windows
C:\> npm install -g phonegap

And you can update the PhoneGap CLI with:

# OS X / Linux
$ sudo npm update -g phonegap
# Windows
C:\> npm update -g phonegap

You can also report issues or send pull requests to our open source repository.

So what’s changed? Let’s take a look!

Version 3.6.3-0.22.0

$ phonegap --version
3.6.3-0.22.0

The update bumps the PhoneGap CLI version to 3.6.3-0.22.0.

Version 3.6.3 states that the Cordova 3.6.3 runtime is used to compile your projects.

Version 0.22.0 states the version of the phonegap-cli node library. Previously, the node library was 0.21.19, but the minor in major.minor.patch has been incremented because new functionality was added. While some commands now have deprecation warnings, they will all still work.

New Commands

The PhoneGap CLI now has access to every command available to the cordova@3.6.3-0.2.13 runtime.

The complete list of new commands are:

$ phonegap compile <platforms>
$ phonegap cordova <command>
$ phonegap emulate <platforms>
$ phonegap info
$ phonegap platform add <platforms>
$ phonegap platform remove <platforms>
$ phonegap platform check
$ phonegap platform list
$ phonegap plugin search <keyword>
$ phonegap prepare <platforms>
$ phonegap save platforms --experimental
$ phonegap save plugins --experimental
$ phonegap restore platforms --experimental
$ phonegap restore plugins --experimental

For example, you can now analyze your dev environment with:

$ phonegap info

Deprecated Commands

In with the new and out with the old!

We still support all of the original PhoneGap CLI commands, but some will soon be deprecated. When you use a deprecated command, you’ll now see a deprecation warning with the suggested alternative.

For example:

$ phonegap install ios
[warning] The command `$ phonegap install` has been DEPRECATED.
[warning] The command has been delegated to `$ phonegap run`.
[warning] The command will soon be removed.

The complete list of deprecated commands are:

$ phonegap install <platform>
$ phonegap local build <platform>
$ phonegap local install <platform>
$ phonegap local run <platform>
$ phonegap local plugin add <platform>
$ phonegap local plugin remove <platform>
$ phonegap local plugin list

Helpful Help

We’ve put a lot of time into updating all of the help documentation.

You can learn about the top-level commands by typing any of the following:

$ phonegap
$ phonegap help
$ phonegap --help
$ phonegap -h

You can then learn about a specific command, such as “create” by typing:

$ phonegap help create
$ phonegap create help
$ phonegap create --help
$ phonegap create -h

Similarly, you can learn about the “plugin add” command by typing:

$ phonegap help plugin add
$ phonegap plugin add help
$ phonegap plugin add --help
$ phonegap plugin add -h

If typing commands isn’t your thing, then you can also read all of the documentation as text files in the repository.

New Create Command Options

The create command now supports the --copy-from and --link-to options.

Using --copy-from:

You can create a new project as a copy of an existing project by using the --copy-from option. This will copy the www/, hooks/, and config.xml from the previous project into your new project.

$ phonegap create my-app --copy-from ../my-other-app

Using --link-to:

If copying isn’t your thing, than you can create links (symbolic-links or shortcuts) to share the www/, and hooks/, and config.xml between two or more projects.

$ phonegap create my-app --link-to ../my-other-app

You can learn more about these options with:

$ phonegap help create

Verbose Output

The PhoneGap CLI chooses to be quiet and only show you what’s needed. However, whenever an error occurs, the CLI will now output as much detail as possible!

If you’d like to see what’s going on under-the-hood, simply add the --verbose flag to any command. Just be prepared for a lot of output!

$ phonegap run ios --verbose

Exit Codes

The PhoneGap CLI now has full exit code support! This is incredibly useful when using the PhoneGap CLI in a build-chain, such as Grunt, Gulp, or a continuous integration setup.

So what good are exit codes? They tell you whether the command successfully worked. The PhoneGap CLI will now return 0 when no error occurred and non-zero when something went wrong, such as a compile error or plugin installation error.

Since exit codes are invisible, you can manually check the exit code of your last command (on OS X or Linux) with $?:

$ phonegap build ios
$ echo $?
0

Automatically Adding Platforms

A fan favourite feature of the PhoneGap CLI is automatically adding a platform whenever you try to build or run it. This means that you don’t need to manually type a command to add each platform.

While this feature has always existed, we had to re-write it from the ground up. Enjoy!

The following two scenarios have identical results:

$ phonegap create my-app/ | $ phonegap create my-app/
$ cd my-app/              | $ cd my-app/
                          | $ phonegap platform add ios
$ phonegap run ios        | $ phonegap run ios

Support for phonegap.js

Way back in the day, before Apache Cordova, there was only PhoneGap. So naturally, you needed to script include phonegap.js. When we donated the majority of PhoneGap’s source code to Apache as Cordova, we switched to cordova.js. However, like the stubborn developers that we are, we’ve always had backwards-compatibile support for phonegap.js.

phonegap.js is still supported, but we hope you’re using cordova.js!

When an app references phonegap.js, the file will be added to your platform project and a deprecation warning will be displayed. In an upcoming release, support for phonegap.js will be dropped!

When an app references cordova.js, the cordova.js file will be added, but phonegap.js will not be added. This has virtually no impact on performance, but it’s one less file :)

config.xml File Location

The config.xml file has moved from the app’s web directory to the app’s root directory. In other words, from my-app/www/ to my-app/. This change is driven by Apache Cordova and respected by PhoneGap and PhoneGap Build.

Unfortunately, the config.xml location can be confusing because of consistencies in paths.

Icon and splash screen paths are now relative to your application’s root directory:

<!-- filepath: myapp/res/icon.png -->
<icon src="res/icon.png" />

However, the content element is relative the web directory:

<!-- filepath: my-app/www/index.html -->
<content src="index.html" />

This is true for any project that is compatible with Apache Cordova.

No --device shorthand option

The PhoneGap CLI now uses -d as shorthand for --verbose. A trick to remember this option is that verbose mode is intended for debugging (-d).

Originally, the PhoneGap CLI used -d as the shorthand option for --device. However, in order to completely algin with the Cordova commands, we had to drop this support.

You can learn more about the top-level and run-level options with:

$ phonegap help
$ phonegap help run

Transparency

We always try explain what’s going on under-the-hood. For example, when you deploy a project for the first time, we explain that we’re adding the platform to your project:

$ phonegap run ios
[phonegap] executing 'cordova platform add ios'...
[phonegap] completed 'cordova platform add ios'
[phonegap] executing 'cordova run ios'...
[phonegap] completed 'cordova run ios'

Programmatic Interface

For those of you that use the PhoneGap CLI as a node module, you’ll be happy to know that we’ve updated the node API with a new interface. You can now call directly into Cordova using:

var phonegap = require('phonegap');
phonegap.cordova({ cmd: 'cordova platform add ios' }, callback);

Direct Line to Cordova

Similar to the programmatic interface above, we provide a direct interface to Cordova on the command-line. As a developer, you should rarely need to use it, but it’s nice to have. :)

Every PhoneGap command is the same as every Cordova command, except for two situations:

  1. Creating a project

You can force the creation of a vanilla Cordova project with:

  $ phonegap cordova create my-app/

Which will be different from a vanilla PhoneGap project:

  $ phonegap create my-app/
  1. Display the Cordova runtime version
  $ phonegap cordova --version
  3.6.3-0.2.13

Which will be different from the PhoneGap version:

  $ phonegap --version
  3.6.3-0.22.0