Cordova-CLI is doing some great things to make working with multiple platforms in one Cordova project easier. But installing with it can initially seem a little daunting if you’ve never played with it before, and so I thought it would help to write this guide up to help anyone else getting their feet wet.

Note: I’m a Mac OS X user. Therefore, I’ve only tested any of this on my Mac. It should translate to Linux fairly easily. Getting anything to work on Windows is probably going to be painful, given that Cordova-CLI indicates it has only been tested on Mac OS X and Linux.

Downloading and Installing node.js

The first thing you need to do is install node.js. This is available at http://nodejs.org/. You can download the Mac OS X package by clicking “Install”.

Once downloaded, double-click the package file, and step through the instructions. node.js will tell you that it is installing to /usr/local/bin and that your PATH will need to be updated to include this.

Updating your PATH

To update your path, you can simply navigate back to your home directory (~) and edit your .profile:

cd ~
vi .profile

Next, the following commands in your .profile will add /usr/local/bin to your path — be sure to add them at the end of your .profile.

# for NODE
PATH="${PATH}:/usr/local/bin"
export PATH

Before you do anything, be sure to close and restart your terminal session, or the PATH won’t be correct. Alternatively, source your .profile:

. ./.profile

Before installing Cordova-CLI

You need to be absolutely certain that you have access to your development tool’s command-line tools via the command line, or the install will error out later on.

You must have the latest version of each development environment installed, or things will most likely go very wrong.

Xcode (iOS) Install Xcode Command Line Tools

Open up Xcode and then navigate to Xcode → Preferences…, then select the Downloads tab. If the Components section isn’t already selected, select that.

Now, near the bottom of the list, there should be a Command Line Tools option with an Install option if it hasn’t already been installed. Click Install to let it download and install.

Only proceed once the components have been fully installed. You may need to restart your terminal as well.

Agree to XCode’s License

Once you’ve got the command line components installed, the you must agree to the Xcode license agreement for all users of the computer.

Open terminal and type:

sudo xcodebuild -license

Enter your password when prompted. Then be sure to [space] through the license, and then type agree at the end.

Android Download Most Recent Android SDK

If you don’t have an Android SDK installed, be sure to download the Android SDK from Google at http://developer.android.com/sdk/index.html.

Be sure you’ve got the most recent version of the Android SDK installed. If you’ve already got a version installed and in the PATH, you can type:

android

Alternatively, just open Eclipse and navigate to Window → Android SDK Manager.

If you have any updates, click the Install # packages… button, then click Accept All to accept all the license agreements, and then click Install.

Add Android Tools To Your PATH

Once again, navigate to your home directory (~) and edit your .profile:

cd ~
vi .profile

Then add this to the end of your .profile:

# for Android
PATH="${PATH}:/Path-To-Android-SDK/android-sdk-macosx/tools:/Path-To-Android-SDK/android-sdk-macosx/platform-tools"
export PATH

Be careful to replace Path-To-Android_SDK with the actual path to your Android SDK. On my Mac, this is under /Applications, but it may be in another spot on your machine.

Before you do anything more, be sure to close and restart your terminal session, or the PATH won’t be correct. Alternatively, source your .profile:

. ./.profile

Installing Cordova-CLI

The install instructions don’t warn you that you need to be root in order to install the package successfully. So, here’s the command I used:

sudo npm install -g cordova

When prompted, be sure to supply your user’s password, and then you should see output that looks like this:

npm http GET https://registry.npmjs.org/cordova
npm http 304 https://registry.npmjs.org/cordova
npm http GET https://registry.npmjs.org/colors
npm http GET https://registry.npmjs.org/elementtree/0.1.3
npm http GET https://registry.npmjs.org/xcode/0.5.1
…

If the install hangs, like mine did, just break the process (CTRL-C), and re-run the installation command.

The final output should look something like this:

SUCCESS: Minimum requirements for blackberry met.
BOOTSTRAPPING blackberry...
SUCCESS: Minimum requirements for ios met.
BOOTSTRAPPING ios...
SUCCESS: ios ready to rock!
SUCCESS: blackberry ready to rock!
SUCCESS: Minimum requirements for android met.
BOOTSTRAPPING android...
SUCCESS: android ready to rock!
**************************************************************************
* WARNING: YOU ARE INSTALLING GLOBALLY INTO A ROOT-ONLY DIRECTORY!!!1one *
* Your node install is global, so global modules get installed there too.*
* You should probably run the following command for this tool to run:    *
    $ sudo chown -R your-user /usr/local/lib/node_modules/cordova
* This will allow you to run this tool globally without using `sudo`.    *
**************************************************************************
cordova@2.5.5 /usr/local/lib/node_modules/cordova
├── ncallbacks@1.0.0
├── colors@0.6.0-1
├── semver@1.1.0
├── shelljs@0.1.2
├── request@2.11.4
├── elementtree@0.1.3 (sax@0.3.5)
├── xcode@0.5.1 (node-uuid@1.3.3, pegjs@0.6.2)
├── prompt@0.2.7 (revalidator@0.1.5, pkginfo@0.3.0, read@1.0.4, utile@0.1.7, winston@0.6.2)
├── express@3.0.6 (methods@0.0.1, fresh@0.1.0, range-parser@0.0.4, cookie-signature@0.0.1, buffer-crc32@0.1.1, cookie@0.0.5, debug@0.7.2, commander@0.6.1, mkdirp@0.3.3, send@0.1.0, connect@2.7.2)
├── plugman@0.5.6 (osenv@0.0.3, bplist-parser@0.0.4, xcode@0.4.2, nopt@1.0.10, glob@3.0.1)
└── plist@0.4.0 (xmlbuilder@0.4.2, xmldom@0.1.13)

If, at any point you see notices that the minimum requirements aren’t met for a particular platform, be sure that you’ve downloaded the most recent version, agreed to any license agreement, and have the correct paths in PATH. You can re-run the installation command any number of times to repeat the process until you have all the minimum requirements met.

If you don’t intend to develop for a specific platform, you don’t need to worry if the install process complains that the minimum requirements aren’t met.

Finally, notice that big warning block in the output? This indicates that since node.js has been installed globally for all users, it currently has permissions that would require that you sudo in order to execute any commands.

Therefore, execute the command as shown in order to make the command friendlier to use:

sudo chown -R your-user /usr/local/lib/node_modules/cordova

Installing iOS Simulator Support

If you intend on using the iOS Simulator from the command line, you aren’t done yet. You need to instal ios-sim first, most easily accomplished using homebrew.

Installing homebrew

You can learn more about homebrew at http://mxcl.github.com/homebrew/, but essentially it requests that you use the following command:

ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"

Let me first say how absolutely I abhor this method of installation. Therefore, be absolutely certain you trust the content of the file being downloaded and then executed before you run this command. I looked at it, and it looks safe enough to me, but you are expected to verify that it will be safe for you. If it turns out that it isn’t, not my fault. Sorry.

It will display a list of things it will do to your system, and then prompts you to press [ENTER] when ready. (Or, press any other key to exit.)

==> This script will install:
/usr/local/bin/brew
… 
==> The following directories will be made group writable:
/usr/local/.
/usr/local/bin
… 
==> The following directories will have their group set to admin:
/usr/local/.
/usr/local/bin
/usr/local/include
… 
Press ENTER to continue or any other key to abort

When it starts to do real work, it will prompt you for your sudo password (assuming the previous sudo attempts have timed out).

You should have output similar to this:

==> /usr/bin/sudo /bin/chmod g+rwx /usr/local/. /usr/local/bin /usr/local/include /usr/local/lib /usr/local/share /usr/local/share/locale /usr/local/share/man /usr/local/share/man/man1 /usr/local/share/man/man5
==> /usr/bin/sudo /usr/bin/chgrp admin /usr/local/. /usr/local/bin /usr/local/include /usr/local/lib /usr/local/share /usr/local/share/locale /usr/local/share/man /usr/local/share/man/man1 /usr/local/share/man/man5
==> Downloading and Installing Homebrew...
remote: Counting objects: 105377, done.
remote: Compressing objects: 100% (44209/44209), done.
remote: Total 105377 (delta 74733), reused 88054 (delta 60267)
Receiving objects: 100% (105377/105377), 15.76 MiB | 229 KiB/s, done.
Resolving deltas: 100% (74733/74733), done.
From https://github.com/mxcl/homebrew
 * [new branch]      master     -> origin/master
HEAD is now at b412fe3 exiftool 9.24
Warning: Install the "Command Line Tools for Xcode": http://connect.apple.com
==> Installation successful!
You should run `brew doctor' *before* you install anything.
Now type: brew help

I’ll be honest as to not knowing why it insists I don’t have Command Line Tools installed — I do.

Next, run brew doctor as it suggests. You’ll receive some warnings (I got plenty), but it is up to you to decide if they are worth fixing or not.

Installing ios-sim

Next, we can install ios-sim

brew install ios-sim

You’ll see output like this:

==> Downloading https://github.com/phonegap/ios-sim/tarball/1.6
######################################################################## 100.0%
==> /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/bin/rake install prefix=/usr/local/Cellar/ios-sim/1.6
   /usr/local/Cellar/ios-sim/1.6: 4 files, 96K, built in 5 seconds

If you run this and you see a mug of beer, yes – that’s normal.

Creating Your First Project

You should now be able to create the project by issuing the following at the command prompt:

cordova create path-to-project/ reverse.domain.name project-name

For example, you might use something like this:

cordova create ./exampleApp demo.example.com exampleApp

After this, you’ll have a directory structure that looks like this:

exampleApp/
    .cordova/
    merges/
    platforms/
    plugins/
    www/
        index.html
        … 

Adding Platforms to your Project

Without any target platforms, the project won’t be going anywhere. Let’s add some:

cd exampleApp
cordova platform add ios android

Now, the directory structure looks like this:

exampleApp/
    .cordova/
    merges/
    platforms/
        ios/
        android/
    plugins/
    www/
        index.html
        … 

Listing Project-supported Platforms

If you ever in the future want to know what platforms a project supports, you can execute cordova platform list:

cordova platform list

The output will be something like this:

[ 'android', 'ios' ]

Removing a Platform

Perhaps you’ve decided to remove a platform from the project. You can remove it very easily:

cordova platform remove android

After which a cordova platform list returns (for our example):

[ 'ios' ]

Compiling a Project

There are several ways you can compile a project.

• use cordova prepare and then cordova compile
• use cordova prepare from the command line, and then use your IDE
• use cordova build from the command line

If you’re working solely from the command line, the latter is probably the easiest method. If, however, you like to use your IDE for building, deployment, and testing, you could always use the second option.

If you only want to compile for one platform (instead of all of them), you can specify the list of platforms, like so:

cordova build ios android

The first and third options above are the same thing. The latter simply does both steps for you.

Emulating a Project

To emulate a project in your platform’s emulator, you can use:

cordova emulate [platform…]

If you don’t specify any platform, you’ll end up emulating the project on every emulator the project is valid for. While this is sometimes the goal, I often test on one platform first, and then move on to the other. So you’ll almost certainly want to specify a single platform:

cordova emulate android

Note: there’s no prompt as to which device you’re going to emulate. You’ll need to have specified that in advance using the appropriate tool in your SDK.

Now, if you try to emulate an iOS device without installing ios-sim, you’ll hit a roadblock:

[Error: An error occurred while emulating/deploying the ios project.Error: ios-sim was not found. Please download, build and install version 1.4 or greater from https://github.com/phonegap/ios-sim into your path. Or "brew install ios-sim" using homebrew: http://mxcl.github.com/homebrew/
]

Why Cordova-CLI doesn’t do this (or prompt to do this) or even warn you at install time is beyond me. Rather it creates a rather rude interruption in your workflow that you have to overcome in order to just test on iOS. Now you know why we installed it ahead of time. But, if like me, you get caught by this error, look above at the section entitled “Installing iOS Simulator Support” and follow the instructions before repeating the emulator command.

Testing using a Webkit Browser

If your app doesn’t rely on any of the Phonegap APIs or use any plugins, you can test the app using a Webkit browser such as Chrome or Safari.

cordova serve platform [port]

Here you must specify a platform (like iOS), so if you’ve made changes to the global www directory, you’ll need to, at a minimum, cordova prepare the platform in question, or you’ll see out-dated content.

The port is optional; it will default to 8000 on its own.

Once started, you’ll see this output:

{}
Static file server running at
  => http://localhost:8000/
CTRL + C to shutdown

Now you can navigate to http://localhost:8000 from your machine, or do the same from any other device (substituting localhost with the proper hostname of your development machine).

Keep in mind that this in no way provides a PhoneGap API or emulation to the project. So even if you access the content from your iPhone, you’ll find that it behaves no better than it would in a browser on your machine. That said, it’s still useful for testing rendering without doing a full deploy on your devices.

When done, you can kill the server using CTRL+C.

Only use cordova serve on development machines behind a firewall. The web server used in this context is not intended to be used in production.

Update your config.xml file

Before you go much further, you’re going to want to check and update your config.xml file. It was created when you used cordova create, and it contains all sorts of properties you’ll need to double-check and change.

The file itself will be in project-directory/www/config.xml and you can edit it using any editor that understands plain text or XML.

You’ll almost certainly want to update the description and author sections to your liking, but you’ll also eventually need to deal with the other properties as well. You can see more about these on PhoneGap’s Documentation Site. You’ll also eventually need to adjust the whitelisting property as well, though by default it allows any external reference.

More, so much more…

There’s far more to Cordova-CLI than what I’ve gone over here. You’ll note that I’ve not covered plugins at all, though I will write an article at some point in the future. In the meantime, if you want the syntax for dealing with plugins, I’ve included it below:

cordova plugin list                -- lists all the plugins in the project
cordova plugin add path-to-plugin… -- adds one or more plugins to the project
cordova plugin remove plugin-name… -- removes one or more plugins from the project.

There are also hooks you can add for each command if you need to integrate your own build system or somehow need them for integrating with your version control system. Regardless, they are beyond the scope of this article.

Comments, thoughts, corrections? Post them below, or feel free to reach out to me via my website or my handle on Twitter or ADN (@photokandy). I’m also pretty active on the Google Group for Phonegap.

Edits

• March 27, 2013 - Tumblr dropped some inline links. Fixed a couple of spelling errors. Thanks to @Steve in the comments!