May 9, 2017
  • All
  • CLI

Announcing Ionic CLI v3

Dan Imhoff

Greetings everyone! I’m happy to announce that version 3 of the Ionic CLI is now available!

Since we announced the CLI v3 Beta and our Easter Egg hunt, we’ve seen a large amount early beta testers using the CLI successfully in their Ionic projects. These testers were able to provide some great feedback, as well as get a chance to win a prize! In fact, many of them found our Easter Egg in just a few short hours. More recently, we were able to get even more feedback while devs became true Ionic Jedi Hacksters in our hackathon last week (Stay tuned for results on our Ionic Jedi Hackathon!!!)

Other than the version change, what makes this CLI release special? Let’s take a look at some of the key improvements to the CLI.

Speed + Guidance

The first thing you may notice is how quickly the new CLI installs. This is partly due to eliminating over 90MB of dependencies and thousands of lines of legacy code! Now when you install the CLI, you get a much smaller footprint as well as a faster install time. Going forward, CLI speed and performance will be one of the primary considerations we have.

Another consideration we had was providing more help, guidance, and feedback. A large number of commands now provide interactive prompts when information is needed. The CLI tries to be informative and helpful when problems arise. Command help has also been improved. Just append --help to any command for a detailed overview of inputs and options. We also provide examples of common use cases. For example, check out the details of ionic start --help:


We took a different approach to the architecture of the CLI. Instead of providing everything in one global install, we split out non-essential commands and functionality into CLI plugins. This keeps the core small, while still offering valuable, project-specific functionality in plugins.

For the first release of CLI v3, there are four official CLI plugins:

  • @ionic/cli-plugin-ionic-angular – Ionic Angular project plugin that provides useful build tools and generators.
  • @ionic/cli-plugin-ionic1 – Ionic 1 project plugin that has functionality ported from the old CLI.
  • @ionic/cli-plugin-cordova – Essential for an Ionic/Cordova app.
  • @ionic/cli-plugin-proxy – For proxying CLI requests through a firewall.

A common question that came up during the beta test was “Why are the commands different?” With the new CLI, we decided to namespace the Cordova commands (e.g. ionic build is now ionic cordova build). We felt this was a necessary change as Ionic developers are beginning to create Ionic apps for desktop, PWAs, and other platforms. To help with the differences, we made you a lovely Cheat Sheet.

Getting Started

Make sure you have Node 6+ and npm 3+.

Install the new CLI globally (after uninstalling the old one):

npm uninstall -g ionic
npm install -g ionic@latest

In your Ionic project directory (and assuming you have a standard Ionic project structure), try running a command, such as ionic info. The CLI attempts to identify your project type and will prompt you to install the respective plugin. If you run ionic cordova, it will prompt you to install the Cordova plugin. If you run ionic --help, you’ll see a list of all commands.

You’ll need both the Cordova plugin (@ionic/cli-plugin-cordova) and the project plugin (@ionic/cli-plugin-ionic-angular or @ionic/cli-plugin-ionic1) to continue developing an existing Ionic/Cordova app:

For Ionic Angular:

npm install --save-dev --save-exact @ionic/cli-plugin-ionic-angular@latest
npm install --save-dev --save-exact @ionic/cli-plugin-cordova@latest

For Ionic 1:

npm install --save-dev --save-exact @ionic/cli-plugin-ionic1@latest
npm install --save-dev --save-exact @ionic/cli-plugin-cordova@latest

The CLI will also occasionally check for updates and prompt you when there’s updates available.

Known Issues

We have a few minor things to improve now that CLI v3 is out.

  • ionic start still takes a long time to download dependencies. (#2231)
  • ionic start does not yet support alternatives such as downloading from a Github repo, a zip URL, or an Ionic Creator project. (#2156)
  • Using ionic cordova commands indent config.xml to 4 spaces, which may be alarming for existing apps. We write to config.xml for resource generation and livereload. (#2230)
  • For Ionic 1, some gulp hooks are not called. (#1989)
  • Uploads from CLI v3 don’t extract properly in Ionic Deploy on Android devices. (#2237)

For a full list of CLI changes, please see For more documentation, please see

Questions? Ideas? Feedback? Issues? Please let us know by filing an issue on the Ionic CLI repo.

THANK YOU to all our wonderful Beta testers! Special thanks to those who went the extra mile and contributed issues, comments, and pull requests on Github. ❤️

Dan Imhoff