1 | # Microsoft Azure Xplat-CLI for Windows, Mac and Linux
|
2 |
|
3 | [![NPM version](https://badge.fury.io/js/azure-cli.png)](http://badge.fury.io/js/azure-cli) [![Build Status](https://travis-ci.org/Azure/azure-xplat-cli.png?branch=master)](https://travis-ci.org/Azure/azure-xplat-cli)
|
4 |
|
5 | This project provides a cross-platform command line interface for developers and IT administrators to develop, deploy and manage Microsoft Azure applications.
|
6 |
|
7 | ## Features
|
8 |
|
9 | * Accounts Management
|
10 | * Azure Service Management
|
11 | * Storage
|
12 | * Websites
|
13 | * Virtual machines
|
14 | * Network
|
15 | * Mobile Services
|
16 | * Service Bus
|
17 | * SQL Database
|
18 | * Azure Resource Management
|
19 | * Generic resource groups and deployments management
|
20 | * Role based access control
|
21 | * Cmdlets for individual resource providers, including compute, storage, network, redis cache, insights, etc.
|
22 | * Datalake
|
23 | * Key Vault
|
24 |
|
25 | For comdlets detail, type "azure" to navigate through the help system. Also, use `azure config mode` to switch between service management and resource management.
|
26 |
|
27 | ## Endpoints for Azure
|
28 |
|
29 | The CLI targets **"Public Azure Cloud"** by default. You can get more information about the endpoints supported in different environments from [here](./Documentation/Endpoints.md).
|
30 |
|
31 | ## Non-Interactive Authentication
|
32 | If you need to create an automation account for non interactive or scripting scenarios then please take a look at the documentation over [here](https://github.com/Azure/azure-sdk-for-node/blob/autorest/Documentation/Authentication.md).
|
33 |
|
34 |
|
35 | ## Installation
|
36 |
|
37 | ### Installation from a particular branch of this repository
|
38 | - Uninstall the previously installed CLI
|
39 | - If you installed via MSI, then uninstall the windows MSI. For mac installer `sudo azure-uninstall -g`
|
40 | - If you installed via npm then execute: `npm uninstall azure-cli –g`
|
41 | - Clear the global cache: `npm cache clear –g`
|
42 | - Delete the .streamline folder from the User’s home profile `C:\Users\<username>\.streamline` | `~/.streamline`, if present.
|
43 | - Download the tarball from this link: `https://github.com/Azure/azure-xplat-cli/archive/<branch-name>.tar.gz`
|
44 | - Install from the tarball: `npm install –g <path to the downloaded tarball>`
|
45 |
|
46 | And you should be good to go :).
|
47 | Note: You may require admin prompt or sudo access to install via npm.
|
48 |
|
49 | ### Install from npm
|
50 |
|
51 | You can install the azure-cli npm package directly.
|
52 | ```bash
|
53 | npm install -g azure-cli
|
54 | ```
|
55 |
|
56 | ### Install on Ubuntu
|
57 | The Xplat-CLI requires Node.js. Installation varies slightly by Ubuntu version.
|
58 |
|
59 | **Ubuntu 14.04 Trusty Tahr**
|
60 |
|
61 | On Ubuntu 14, the Node.js package is called nodejs-legacy. The npm package is installed first to get the Node Package Manager used to install the CLI.
|
62 |
|
63 | ```bash
|
64 | sudo apt-get install nodejs-legacy
|
65 | sudo apt-get install npm
|
66 | sudo npm install -g azure-cli
|
67 | ```
|
68 | **Ubuntu 12.04 Precise Pangolin**
|
69 |
|
70 | On Ubuntu 12, the version of Node.js available in the default package manager is too old. You can use the Personal Package Archive feature to install the current binary distribution. First, install the curl package to easily retrieve the install script.
|
71 |
|
72 | ```bash
|
73 | sudo apt-get install curl
|
74 | curl -sL https://deb.nodesource.com/setup | sudo bash -
|
75 | sudo apt-get install -y nodejs
|
76 | sudo npm install -g azure-cli
|
77 | ```
|
78 |
|
79 | ### Install on a Docker Host
|
80 |
|
81 | In a Docker host, run:
|
82 | ```bash
|
83 | sudo docker run -it microsoft/azure-cli
|
84 | ```
|
85 |
|
86 | ### Pre-compiled installers
|
87 |
|
88 | * [Windows](http://aka.ms/webpi-azure-cli)
|
89 | * [Mac](http://aka.ms/mac-azure-cli)
|
90 | * [Linux](http://aka.ms/linux-azure-cli)
|
91 |
|
92 |
|
93 | ### Configure auto-complete
|
94 |
|
95 | Auto-complete is supported for Mac and Linux.
|
96 |
|
97 | To enable it in zsh, run:
|
98 |
|
99 | ```bash
|
100 | echo '. <(azure --completion)' >> .zshrc
|
101 | ```
|
102 |
|
103 | To enable it in bash, run:
|
104 |
|
105 | ```bash
|
106 | azure --completion >> ~/azure.completion.sh
|
107 | echo 'source ~/azure.completion.sh' >> ~/.bash_profile
|
108 | ```
|
109 |
|
110 | ## Get Started
|
111 |
|
112 | * First, get authenticated with Microsoft Azure. For details, read [this article](http://azure.microsoft.com/en-us/documentation/articles/xplat-cli/).
|
113 | * Option 1: Login with your Microsoft account, such as live-id, or organizational account, or service principals.
|
114 | * Option 2: Download and import a publish settings file which contains a management certificate.
|
115 |
|
116 | If you use both mechanisms on the same subscription, Azure Active Directory authentication will be used by default. If you want to go back to management certificate authentication, please use ``azure logout``, which will remove the Azure Active Directory information and bring management certificate authentication back in.
|
117 |
|
118 | #### Login directly from xplat-cli (Azure Active Directory authentication)
|
119 |
|
120 | ```bash
|
121 | # This will output an url and a device code for you to use browser to login
|
122 | azure login
|
123 |
|
124 | # This will prompt for your password in the console
|
125 | azure login -u <your organizational ID email address>
|
126 |
|
127 | # This will login in using a service principal
|
128 | azure login -u "<service-principal-id>" -p "<key>" --service-principal --tenant "<tenant-id>"
|
129 | ```
|
130 |
|
131 | #### Use publish settings file (Management certificate authentication)
|
132 |
|
133 | ```bash
|
134 | # Download a file which contains the publish settings information of your subscription.
|
135 | # This will open a browser window and ask you to log in to get the file.
|
136 | azure account download
|
137 |
|
138 | # Import the file you just downloaded.
|
139 | # Notice that the file contains credential of your subscription so you don't want to make it public
|
140 | # (like check in to source control, etc.).
|
141 | azure account import <file location>
|
142 |
|
143 | # Use the commands to manage your services/applications
|
144 | azure site create --location "West US" mywebsite
|
145 | ```
|
146 |
|
147 | ### azure cli with China Cloud
|
148 | ```bash
|
149 | # This will log you into the China Cloud environment.
|
150 | # You can use same set of commands to manage your service/applications
|
151 | azure login -u <your organizational ID email address> -e AzureChinaCloud
|
152 | ```
|
153 |
|
154 | ### azure cli on Ubuntu
|
155 | If you want to run xplat cli on Ubuntu, then you should install **nodejs-legacy** instead of **nodejs**. For more information please check the following links:
|
156 | - [why there is a problem with nodejs installation on ubuntu](http://stackoverflow.com/questions/14914715/express-js-no-such-file-or-directory/14914716#14914716)
|
157 | - [how to solve the nodejs installation problem on ubuntu](https://github.com/expressjs/keygrip/issues/7)
|
158 |
|
159 | Please perform the installation steps in following order:
|
160 | ```bash
|
161 | sudo apt-get install nodejs-legacy
|
162 | sudo apt-get install npm
|
163 | sudo npm install -g azure-cli
|
164 | ```
|
165 |
|
166 | ## 2 Modes
|
167 |
|
168 | Starting from 0.8.0, we are adding a separate mode for Resource Manager. You can use the following command to switch between the
|
169 |
|
170 | * Service management: commands using the Azure service management API
|
171 | * Resource manager: commands using the Azure Resource Manager API
|
172 |
|
173 | They are not designed to work together.
|
174 |
|
175 | ```bash
|
176 | azure config mode asm # service management
|
177 | azure config mode arm # resource manager
|
178 | ```
|
179 |
|
180 | **For more details on the commands, please see the [command line tool reference](http://go.microsoft.com/fwlink/?LinkId=252246&clcid=0x409) and this [How to Guide](http://azure.microsoft.com/en-us/documentation/articles/xplat-cli/)**
|
181 |
|
182 | ## Docker
|
183 |
|
184 | Usage is the same as `vm create` command:
|
185 |
|
186 | azure vm docker create [options] <dns-name> <image> <user-name> [password]
|
187 |
|
188 | This command only supports Ubuntu 14.04+ and CoreOS based images. Docker is configured on the VM using HTTPS as described here: https://docs.docker.com/articles/https/ By default, generated TLS certificates are placed in the `~/.docker` directory, and Docker is configured to run on port 2376. These can be configured using new options:
|
189 |
|
190 | -dp, --docker-port [port] Port to use for docker [2376]
|
191 | -dc, --docker-cert-dir [dir] Directory containing docker certs [~/.docker/]
|
192 |
|
193 | After the VM is created. It can be used as a Docker host with the `-H` option or `DOCKER_HOST` environment variable.
|
194 |
|
195 | docker --tls -H tcp://<my-host>.cloudapp.net:2376 info
|
196 |
|
197 | Note: To run docker commands on windows make sure ssl agent is installed.
|
198 |
|
199 | ## Error Diagnostic
|
200 |
|
201 | ### use the -vv option to see the actual REST requests on the console.
|
202 | ```bash
|
203 | azure site create --location "West US" mytestsite -vv
|
204 | ```
|
205 |
|
206 | ### Use web debugging proxy
|
207 | Say, use 'Fiddler', setup the following environment variables before execute commands.
|
208 |
|
209 | ```bash
|
210 | set NODE_TLS_REJECT_UNAUTHORIZED=0
|
211 | set HTTPS_PROXY=http://127.0.0.1:8888
|
212 | ```
|
213 |
|
214 | ## Running Tests
|
215 |
|
216 | See [this page for instructions](https://github.com/Azure/azure-xplat-cli/wiki/Running-Tests) that describe how to run the test suite.
|
217 |
|
218 | ## Learn More
|
219 | For documentation on how to host Node.js applications on Microsoft Azure, please see the [Microsoft Azure Node.js Developer Center](http://www.windowsazure.com/en-us/develop/nodejs/).
|
220 |
|
221 | ## Contribute Code or Provide Feedback
|
222 |
|
223 | If you would like to become an active contributor to this project please follow the instructions provided in [Microsoft Azure Projects Contribution Guidelines](http://azure.github.io/guidelines/).
|
224 |
|
225 | Please send pull requests only to the **Dev branch**. Please make sure that you have checked in tests and recorded them live for your contribution. **Pull requests without sufficient tests will not be accepted.**
|
226 |
|
227 | If you encounter any bugs with the library please file an issue in the [Issues](https://github.com/Azure/azure-xplat-cli/issues) section of the project.
|