How to use the MAAS CLI (snap/3.1/CLI)
The MAAS CLI can do everything that the web UI can do, and more. The CLI uses the
maas command exclusively which, in turn, connects to the API. This page explains what is needed to get started with the CLI. You can obtain the MAAS CLI from the
maas-cli Ubuntu package installed on every region API server and rack controller.
Immediately after installing the MAAS CLI, you will need to create an administrator account, in order to access most of the CLI features. You can also create regular users, as desired.
As a security measure, MAAS generates an API key when creating your MAAS account, which you must use when logging in. This API key can be obtained via a special command to the MAAS CLI. You can obtain a user’s API key from the web interface.
For additional MAAS CLI commands, you can consult the MAAS CLI help or access the CLI versions of the pages listed in the left-hand navigation. MAAS has a thorough built-in help reference, which you can access in stages to understand how to build commands. The
maas command accepts the
--help argument after every keyword and will display results with increasing detail as you add elements to the help request.
This article will show you:
- How to install the MAAS CLI?
- How to create an administrator account
- How to obtain the administrator’s API key
- How to obtain a user’s API key
- How to login to the MAAS CLI
- How to create a MAAS CLI login shellscript
- How to get help from the MAAS CLI
- How to log out of the MAAS CLI
To install the MAAS CLI, execute this command:
sudo apt install maas-cli
You can create one or more MAAS CLI administrator accounts like this:
sudo maas createadmin --username=$PROFILE --email=$EMAIL_ADDRESS
Be sure to substitute your desired administrative username for $PROFILE, and substitute an email address from $EMAIL_ADDRESS. Note that the $EMAIL_ADDRESS, while required to create an administrator, is not currently used by MAAS.
To obtain the API key needed by an administrator, run this command on the region controller:
sudo maas apikey --username=$PROFILE > $API_KEY_FILE
$PROFILE should be replaced with the administrator username you created; substitute a filename for $API_KEY_FILE.
To obtain a user’s API key, click on ‘username’ in the top right corner of any MAAS screen (when logged in), and select ‘Account’.
To log in to the MAAS CLI, execute the following command on the API server (the region controller):
maas login $PROFILE $MAAS_URL - < $API_KEY_FILE
$PROFILE is the administrator username you’re using to log in. The $MAAS_URL is the URL shared with you when you initialised MAAS (e.g.,
http://localhost:5240/MAAS/api/2.0). $API_KEY_FILE is the name of the file where you stored the API KEY when you requested it from the CLI.
To create a MAAS login shellscript, say
maas-login.sh, enter the following into a file with your favorite text editor:
#!/bin/sh # Change these 3 values as required PROFILE=admin API_KEY_FILE=/home/ubuntu/tmp/api_key API_SERVER=localhost MAAS_URL=http://$API_SERVER/MAAS/api/2.0 maas login $PROFILE $MAAS_URL - < $API_KEY_FILE
You must change the permissions on this file to make it executable with the
chmod command. Also, for best results, make sure to place the script in directory that’s part of your
To get help from the MAAS CLI, enter the following command:
maas $PROFILE --help
Substitute your administrator username for $PROFILE. You will receive a list of all commands.
Add more elements to the help request to receive more detailed help. For example, to get help on the
tags command, enter:
maas $PROFILE tags --help
To get help on creating a tag, enter:
maas admin tags create --help
To continue refining your help request, keep adding more elements as they become visible in the latest help output.
You can log out of the MAAS CLI with the following command:
maas logout $PROFILE
Substitute $PROFILE for the name of the administrative user who is logging off.