Installation
There are a few basic requirements you'll need prior to installing the PhoneGap CLI:
- Node.js - a JavaScript runtime to build your JavaScript code
- git - used in the background by the CLI to download assets. It comes pre-installed on some operating systems. You can check if it's already installed by typing
gitfrom the command line.
Install via npm
Run the following command to install the latest version of the PhoneGap CLI:
$ npm install -g phonegap
Installing a Specific Version
You can install a specific version of the PhoneGap CLI via
npm by specifying the version number after the @symbol:$ npm install -g phonegap@5.1.1
TIP: To get a listing of the PhoneGap CLI versions available, you can run
$ npm info phonegap
If you get an
EACCES error when running any of the commands here, try prefixing it with sudo, such as: $ sudo npm install -g phonegapCreate an App
Create a new application project at the provided path. You can optionally specify a name and package ID via the options parameters listed below, or configure it in the config.xml file after project creation.
Usage
phonegap create [options] <path> [id [name [config]]]
You can specify some options when creating your project, including a template to use as a base project or an existing project to copy from or symbolically link to on your hard drive. Use the
template listcommand to view the templates currently available.Options
--name, -n <name> application name (default: "Hello World")
--id, -i <package> package name (default: "com.phonegap.hello-world")
--template <name> create app using an existing app template
--copy-from, -src <path> create project using a copy of the www folder from an existing project
--link-to <path> symlink/shortcut to the www folder of another project without copying
Config Parameter
The
[config] parameter allows you to pass a JSON string with configuration parameters some plugins may specifically rely on. They are injected into the <path>/.cordova/config.json file.Examples
$ phonegap create path/to/myApp
$ phonegap create path/to/myApp "com.example.app" "My App"
$ phonegap create path/to/myApp --id "com.example.app" --name "My App"
$ phonegap create path/to/myApp --template hello-world
$ phonegap create path/to/myApp --copy-from ../myOtherApp
$ phonegap create path/to/myApp -src ../myOtherApp
$ phonegap create path/to/myApp --id "com.example.app" --name "My App" --copy-from ~/myOtherApp
$ phonegap create path/to/myApp --link-to ../myOtherApp
Note: Check out the templates guide for more details on how to create applications based on templates.
Serve an App ( Run On Browser )
The
serve command is used to start up a local web server to host the application for the PhoneGap Developer app (or any browser) to consume.Usage
phonegap serve [options]
Options
Some options are available for specifically setting the port to use, to enable or disable auto reload, or to setup a local tunnel for public access as shown below.
--port, -p <n> port for web server (default: 3000)
--autoreload enable app refresh on file changes (default: true)
--no-autoreload disable app refresh on file changes
--browser enable desktop browser support (default: true)
--no-browser disable desktop browser support
--localtunnel enable a local tunnel for public access (default: false)
Alias
$ phonegap app
Examples
$ phonegap serve
$ phonegap serve --port 1337
$ phonegap serve --no-autoreload
$ phonegap serve --browser
$ phonegap serve --no-browser
$ phonegap serve --localtunnel
$ phonegap app
Update Version
Manually Update
To update your PhoneGap CLI to the latest version, run the following command:
$ npm install -g phonegap
NOTE: If you get an
Error: EACCES when running any of the commands here, try prefixing it with sudo, such as: $ sudo npm install -g phonegapUpdate Available Notification
The CLI will also display a notification when any command is used if an update is available:
$ phonegap -v
6.0.3
---------------------------------------
| |
| Update available 6.0.3 -> 6.0.4 |
| Run npm i -g phonegap to update |
| |
---------------------------------------
NOTE: This notification will only be displayed once every 24 hours.
To disable the update notifier, you can do one of the following:
- Use the
--no-update-notiferflag with any PhoneGap command.- For example,
phonegap run ios --no-update-notifier
- For example,
- Disable the update notifier by altering the configuration file.
- Open
~/.config/configstore/update-notifier-phonegap.json - Set the property
"optOut": true
- Open
Push Notifications
The
push command is used to send push notifications for the PhoneGap Developer app to consume. Available since version 6.2.0.Usage
phonegap push [options]
Options
Some options are available for specifically setting the device to send to, the type of service to use and the data to send to the application.
--deviceID <deviceID> device ID (required)
--service <service> target service, "gcm", "apns" or "apns-sandbox" (required)
--payload <data> JSON object to be sent via push service (required)
Examples
$ phonegap push --deviceID APA91bE1MmeTc92igNoi5OkDWUV --service gcm --payload '{ "data": { "title": "Hello", "message": "World"} }'
$ phonegap push --deviceID APA91bE1MmeTc92igNoi5OkDWUV --service apns --pa
Templates
Use the
template list command to get a listing of the templates available for creating your applications with the create command. Some templates available include a blank template, a hello-world template or one based on jQuery Mobile. Once you choose a template, specify it using the --template (or the alias --recipe) option followed by the name of the template.Usage
phonegap template list
Examples
$ phonegap template list
$ phonegap create myApp --template hello-world
$ phonegap create myApp --recipe hello-world
Remote Usage
The PhoneGap
remote commands are used for executing commands against the PhoneGap Build service in the cloud rather than relying on a locally installed SDK for each platform.Usage
phonegap remote [command]
Use the commands below in conjunction with the
remote command to perform the specific actions outlined below.Commands
login login to PhoneGap Build (requires an account and your credentials)
logout logout of PhoneGap Build
build <platform> build a specific platform
install <platform> install a specific platform (returns a generated QR code in the terminal)
run <platform> build and install a specific platform
Examples
$ phonegap remote login
$ phonegap remote build ios
$ phonegap remote install android
$ phonegap remote run ios
$ phonegap remote logout
NOTE: You'll need to have an existing PhoneGap Build account to use these commands. You'll be prompted to enter your credentials after running the
$ phonegap remote login command. An Adobe ID can be used as well.
TIP: The
phonegap remote run command will execute both the build and installcommands automatically and is the quickest path to building your app with the PhoneGap Build cloud service. The result is a QR code that can be scanned by your mobile device directly from the terminal to install the app.Cordova Commands
There are some cases where the PhoneGap CLI and Cordova CLI have similar commands but behave differently. The PhoneGap
serve command is a good example of this. Another difference is found when using the phonegap build or phonegap run commands versus the Cordova CLI equivalent. The PhoneGap CLI version will automatically add the platform target if it doesn't already exist.
When you want to specifically enforce the
cordova version of a command, you can add cordova as the prefix to that command. The Cordova CLI version of a command will automatically be used for any commands that are not enhanced by the PhoneGap CLI without having to specifically type cordova.Usage
phonegap cordova <command>
Example
$ phonegap cordova serve
