From version 3.0 onward, Cordova implements all device APIs as
plugins, and leaves them disabled by default. It also supports two
different ways to add and remove plugins. The first is by using the
cordova CLI described in The Command-Line Interface. The second is
by using a lower-level
command-line interface ("Native platform dev" workflow.) The main difference between these two development
paths is that Plugman can only add plugins to one platform at a time, whereas the CLI will add plugins
to all of the platforms that you are targeting. Because of this, it makes more sense to use Plugman when
you are working closely with a single platform, hence the "Native Platform Dev" name of the workflow.
For more information on Plugman, especially if you are interested in consuming Plugman as a node module or hacking on the Plugman code, see the README file in its repository.
To install plugman, you must have node installed on your machine. Then you can run the following command from anywhere in your environment to install plugman globally, so that it is available from any directory on your machine:
$ npm install -g plugman
You must have also have
git on your
PATH to be able to install plugins directly from remote git URLs.
TIP: If you find that after installing plugman with npm you are still unable to run any
plugman commands, make sure that you have
/npm/ directory into your
NOTE: You can skip this step if you don't want to pollute your global npm namespace by installing Plugman globally. If this is the case, then
when you create a Cordova project with the shell tools, there will be a
node_modules directory inside your project which contains Plugman.
Since you did not instally globally, you will have to invoke node for every Plugman command, for example
node ./node_modules/plugman/main.js -version.
The rest of this guide assumes you have installed Plugman globally, meaning you can invoke it with just
Before you can use Plugman, you must create a Cordova project. You can do this with either the Command-line Interface or with the lower level shell scripts. Instructions for using the shell scripts to create your project are located in the various "Command-line Tools" guides listed on the Platform Guides page.
Once you have installed Plugman and have created a Cordova project, you can start adding plugins to the platform with:
$ plugman --platform <ios|amazon-fireos|android|blackberry10|wp7|wp8> --project <directory> --plugin <name|url|path> [--plugins_dir <directory>] [--www <directory>] [--variable <name>=<value> [--variable <name>=<value> ...]]
Using minimum parameters, this command installs a plugin into a cordova project. You must specify a platform and cordova project location for that platform. You also must specify a plugin, with the different
--plugin parameter forms being:
name: The directory name where the plugin contents exist. This must be an existing directory under the
--plugins_dirpath (see below for more info) or a plugin in the Cordova registry.
url: A URL starting with https:// or git://, pointing to a valid git repository that is clonable and contains a
plugin.xmlfile. The contents of this repository would be copied into the
path: A path to a directory containing a valid plugin which includes a
plugin.xmlfile. This path's contents will be copied into the
<project>/cordova/plugins, but can be any directory containing a subdirectory for each fetched plugin.
--wwwdefaults to the project's
wwwfolder location, but can be any directory that is to be used as cordova project application web assets.
--variableallows to specify certain variables at install time, necessary for certain plugins requiring API keys or other custom, user-defined parameters. Please see the plugin specification for more information.
To uninstall a plugin, you simply pass the
--uninstall flag and provide the plugin ID.
$ plugman --uninstall --platform <ios|amazon-fireos|android|blackberry10|wp7|wp8> --project <directory> --plugin <id> [--www <directory>] [--plugins_dir <directory>]
Plugman features a global help command which may help you if you get stuck or are experiencing problems. It will display a list of all available Plugman commands and their syntax:
plugman -help plugman # same as above
plugman -help may show some additional registry-related commands. These commands are for plugin developers and may not be implemented on third-party plugin registries.
You can also append the
--debug|-d flag to any Plugman command to run that command in verbose mode, which will display
any internal debugging messages as they are emitted and may help you track down problems like missing files.
# Adding Android battery-status plugin to "myProject": plugman -d --platform android --project myProject --plugin org.apache.cordova.battery-status
Finally, you can use the
--version|-v flag to see which version of Plugman you are using.
There are a number of plugman commands that can be used for interacting with the Plugin registry. Please note that these registry commands are specific to the plugins.cordova.io plugin registry and may not be implemented by third-party plugin registries.
Searching for a Plugin
You can use Plugman to search the Plugin registry for plugin id's that match the given space separated list of keywords.
plugman search <plugin keywords>
Changing the Plugin Registry
You can get or set the URL of the current plugin registry that plugman is using. Generally you should leave this set at http://registry.phonegap.com unless you want to use a third party plugin registry.
plugman config set registry <url-to-registry> plugman config get registry
Get Plugin Information
You can get information about any specific plugin stored in the plugin repository with:
plugman info <id>
This will contact the plugin registry and fetch information such as the plugin's version number.
The examples below show how to add plugins as needed so that any Cordova APIs you use in your project still work after you upgrade to version 3.0. For each command, you need to select the target platform, and reference the platform's project directory.
--project --plugin org.apache.cordova.battery-status
cordova-plugin-camera plugman --platform
--project --plugin org.apache.cordova.camera
cordova-plugin-console plugman --platform
--project --plugin org.apache.cordova.console
cordova-plugin-contacts plugman --platform
--project --plugin org.apache.cordova.contacts
cordova-plugin-device plugman --platform
--project --plugin org.apache.cordova.device
cordova-plugin-device-motion (accelerometer) plugman --platform
--project --plugin org.apache.cordova.device-motion
cordova-plugin-device-orientation (compass) plugman --platform
--project --plugin org.apache.cordova.device-orientation
cordova-plugin-dialogs plugman --platform
--project --plugin org.apache.cordova.dialogs
cordova-plugin-file plugman --platform
--project --plugin org.apache.cordova.file
cordova-plugin-file-transfer plugman --platform
--project --plugin org.apache.cordova.file-transfer
cordova-plugin-geolocation plugman --platform
--project --plugin org.apache.cordova.geolocation
cordova-plugin-globalization plugman --platform
--project --plugin org.apache.cordova.globalization
cordova-plugin-inappbrowser plugman --platform
--project --plugin org.apache.cordova.inappbrowser
cordova-plugin-media plugman --platform
--project --plugin org.apache.cordova.media
cordova-plugin-media-capture plugman --platform
--project --plugin org.apache.cordova.media-capture
cordova-plugin-network-information plugman --platform
--project --plugin org.apache.cordova.network-information
cordova-plugin-splashscreen plugman --platform
--project --plugin org.apache.cordova.splashscreen
cordova-plugin-vibration plugman --platform
--project --plugin org.apache.cordova.vibration