The Ionic Framework command line utility makes it easy to start, build, run, and emulate Ionic apps. In addition, it comes with (optional!) integration with the Ionic Cloud, a set of mobile backend services perfect for Ionic apps.

Use the ionic --help command for more detailed task information.

$ npm install -g ionic@beta

*Note: For a global install of -g ionic, OSX/Linux users may need to prefix the command with sudo or can setup proper file permissions on OSX for npm to install without sudo. *

Please ensure that you have NodeJS 6+ installed. This is the new LTS version of Node.

We have rewritten the CLI from the ground up. Our main focus was to:

1. Decrease the amount of time to the first start execution
2. Improve the responsiveness of every CLI command
3. Make the architecture flexible for future platform support (PWA, electron, etc.)
4. Provide better help, more guidance, and more feedback when executing commands.

In doing so we decided to take a new approach to the CLI's structure. The base CLI installation now ships with commands that are common all Ionic Applications. These include: start, info, login, signup, help, and version. All other commands are specific to an Ionic project version.

So what does this mean for developers? There are now 2 common plugins that are installed when starting a new Ionic v2 project. These are @ionic/cli-plugin-core and @ionic/cli-plugin-cordova (Below is a list of commands for each plugin). The core plugin contains commands that are common to all Ionic v2 projects and the cordova plugin contains commands that are specific to creating applications with cordova.

If you use CLI v3 to start a new project these plugins are installed automatically. If you are using the CLI v3 on an existing project you will need to install these new plugins within your project directory.

$ npm install -g ionic@beta

$ ionic start myproject blank

Note: If you do not pass an inputs to the start command you will get an interactive prompt that allows you to provide a name and select from a list of starter templates.

$ npm install --save-dev @ionic/cli-plugin-core@beta @ionic/cli-plugin-cordova@beta

$ ionic help

We are currently developing a plugin for Ionic1 applications but it is currently not available for beta. Please note that if you install Ionic CLI v3 you will not be able to work on Ionic1 applications until this plugin is released. Because of this we recommend that if you regularly work on Ionic1 applications you should stick with Ionic CLI v2 for now.

We are currently actively seeking feedback from those that use CLI v3 Beta. If you have questions or issues please feel free to open a new issue. Just be sure to note that you are using CLI v3 Beta.

If your question is about functionality please be sure to start with the help command.

Named template starters:

• blank
• tabs (Default)
• sidemenu
• conference
• tutorial

Automatically generate icons and splash screens from source images to create each size needed for each platform, in addition to copying each resized and cropped image into each platform's resources directory. Source images can either be a png, psd Photoshop or ai Illustrator file. Images are generated using Ionic's image resizing and cropping server, instead of requiring special libraries and plugins to be installed locally.

Since each platform has different image requirements, it's best to make a source image for the largest size needed, and let the CLI do all the resizing, cropping and copying for you. Newly generated images will be placed in the resources directory at the root of the Cordova project. Additionally, the CLI will update and add the correct <platform> configs to the project's config.xml file.

During the build process, Cordova (v3.6 or later) will look through the project's config.xml file and copy the newly created resource images to the platform's specific resource folder. For example, Android's resource folder can be found in platforms/android/res, and iOS uses platforms/ios/APP_NAME/Resources.

Save an icon.png, icon.psd or icon.ai file within the resources directory at the root of the Cordova project. The icon image's minimum dimensions should be 192x192 px, and should have no rounded corners. Note that each platform will apply it's own mask and effects to the icons. For example, iOS will automatically apply it's custom rounded corners, so the source file should not already come with rounded corners. This Photoshop icon template provides the recommended size and guidelines of the artwork's safe zone.

$ ionic resources --icon

• Photoshop Icon Template

Save a splash.png, splash.psd or splash.ai file within the resources directory at the root of the Cordova project. Splash screen dimensions vary for each platform, device and orientation, so a square source image is required the generate each of various sizes. The source image's minimum dimensions should be 2208x2208 px, and its artwork should be centered within the square, knowning that each generated image will be center cropped into landscape and portait images. The splash screen's artwork should roughly fit within a center square (1200x1200 px). This Photoshop splash screen template provides the recommended size and guidelines of the artwork's safe zone. Additionally, when the Orientation preference config is set to either landscape or portrait mode, then only the necessary images will be generated.

$ ionic resources --splash

• Photoshop Splash Screen Template

To generate both icons and splash screens, follow the instructions above and run:

$ ionic resources

One source image can be used to generate images for each platform by placing the file within the resources directory, such as resources/icon.png. To use different source images for individual platforms, place the source image in the respective platform's directory. For example, to use a different icon for Android, it should follow this path: resources/android/icon.png, and a different image for iOS would use this path: resources/ios/icon.png.

By default the ionic resources command will automatically figure out which platforms it should generate according to what platforms have been added to your project. However, you can also explicitly state which resources should be built by providing a platform name in the command. The example below would generate only ios resources (even if the platform hasn't been added to the project).

$ ionic resources ios

Ionic provides you some default icons and splash screens to give you a better idea of how to size your icons and splashscreen, as well as how to modify your config.xml file for your own icons.

$ ionic resources

If you already have a resources directory, the command above will not over write your files. If you wish to force an over write, use ionic resources --default --force.

When starting a new app and adding a platform ionic platform add ios - the default icons and splashscreens will be downloaded and your config.xml will be modified to set up the default resources. This should help you identify your Ionic apps easier as well as help you get the file structure and configuration correct.

Service Proxies:

The serve command can add some proxies to the http server. These proxies are useful if you are developing in the browser and you need to make calls to an external API. With this feature you can proxy request to the external api through the ionic http server preventing the No 'Access-Control-Allow-Origin' header is present on the requested resource error.

In the ionic.project file you can add a property with an array of proxies you want to add. The proxies are object with the following properties:

• path: string that will be matched against the beginning of the incoming request URL.
• proxyUrl: a string with the url of where the proxied request should go.
• proxyNoAgent: (optional) true/false, if true opts out of connection pooling, see HttpAgent

{
  "name": "appname",
  "email": "",
  "app_id": "",
  "proxies": [
    {
      "path": "/v1",
      "proxyUrl": "https://api.instagram.com/v1"
    }
  ]
}

Using the above configuration, you can now make requests to your local server at http://localhost:8100/v1 to have it proxy out requests to https://api.instagram.com/v1

For example:

angular.module('starter.controllers', [])
.constant('InstagramApiUrl', '')
// .contant('InstagramApiUrl','https://api.instagram.com')
//In production, make this the real URL

.controller('FeedCtrl', function($scope, $http, InstagramApiUrl) {

  $scope.feed = null;

  $http.get(InstagramApiUrl + '/v1/media/search?client_id=1&lat=48&lng=2.294351').then(function(data) {
    console.log('data ' , data)
    $scope.feed = data;
  })

})

See also this gist for more help.

Command-line flags/options:

[--consolelogs|-c] ......  Print app console logs to Ionic CLI
[--serverlogs|-s] .......  Print dev server logs to Ionic CLI
[--port|-p] .............  Dev server HTTP port (8100 default)
[--livereload-port|-i] ..  Live Reload port (35729 default)
[--nobrowser|-b] ........  Disable launching a browser
[--nolivereload|-r] .....  Do not start live reload
[--noproxy|-x] ..........  Do not add proxies
[--address] .............  Serves in the browser at the specified address
[--lab] .................  Serves both iOS and Android in the browser
[--nogulp] ..............  Serve without running gulp tasks
[--platform|-t] .........  Serve the platform specific styles in the browser (ios/android)

We've extended the serve command to open the new Lab UI that features iOS and Android side-by-side.

$ ionic serve --lab

If you've used the serve command before, you'll feel right at home with this one. Just like serve, it opens your app in a browser, but now it shows you what your app will look like on a phone, with both iOS and Android side by side.

And of course, it supports Live Reload and all the other goodies we've added over the last couple of months.

Using Ionic's service, you can compile and package your project into an app-store ready app without requiring native SDKs on your machine.

$ ionic package debug android

The third argument can be either debug or release, and the last argument can be either android or ios.

Ionic uses Cordova underneath, so you can also substitute Cordova commands to prepare/build/emulate/run, or to add additional plugins.

Note: we occasionally send anonymous usage statistics to the Ionic team to make the tool better.

If you have a proxy you need to get around, you can pass that proxy with the default http_proxy node environment variable or an environment variable proxy.

A few ways to set up and use the environment variable:

export http_proxy=internal.proxy.com
# Or
export PROXY=internal.proxy.com

ionic start my_app

# Additionally, pass in line
PROXY=internal.proxy.com ionic start my_app

The CLI integrates with Ionic Cloud, a set of backend services that integrate perfectly with Ionic apps. To get started, visit the Ionic Cloud homepage and sign up.

There are a few things you can utilize the CLI for to support ease of development.

Type ionic login to get logged in the CLI.

You can pass the email and password to login without being prompted for email and password.

ionic login [email protected] somepass

The CLI also supports settings environment variables to read off the email and password for the user.

Set IONIC_EMAIL and IONIC_PASSWORD as variables to have the CLI read these instead of being prompted for them.

Use the ionic upload command to take your current application you are developing and upload it to the Ionic.io servers.

Now you can use the ionic view app to view that application or have others view the application.

After uploading the application, you will see a message:

Uploading app....

Successfully uploaded (f23j9fjs)

This indicates you uploaded the application correctly, and the App ID is set to f23j9fjs.

You can then view that App ID from the View app or the application listing on your Ionic Cloud dashboard.

To add a note to your build, pass the --note option as follows:

ionic upload --note "This version of the application fixes the menu selections".

Use the ionic link <appId> command to set your Ionic App ID to continue working with the same app with the Ionic platform across development enviroments.

To get Ionic documentation from the Ionic CLI, try using the ionic docs command. The command will look up your currently used Ionic version and open the docs specific for that version. Ex: RC0, RC1, etc.

To view all docs, ionic docs ls.

To get help with a doc you may not remember, just type the name close enough: ionic docs list and you will be prompted for suggestions that may match.

First class support has come to the Ionic CLI to scaffold and generate Ionic and Angular 2 components. To use this feature, first install the V2 Ionic CLI: npm install ionic@alpha and start an app.

Once in the app folder, use the generate command (alias: g).

Usage:

• ionic generate page About - Generate a page named About with HTML, JavaScript, and Sass named about.
• ionic g tabs MyTabPage - Generate a page named MyTabPage, queries for the amount of tabs, and creates pages for those tabs.

List:

View all generators: ionic g --list.