How to use the MAAS CLI (snap/2.9/UI)

2.9 3.0 3.1
DEB CLI ~ UI CLI ~ UI CLI ~ UI
SNAP CLI ~ UI CLI ~ UI CLI ~ UI

About the MAAS 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 -h or --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 do install the MAAS CLI

To install the MAAS CLI, execute this command:

sudo apt install maas-cli

How to create an administrator account

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.

How to obtain the administrator’s API key

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.

How to obtain a user’s API key

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’.

How to log into the MAAS CLI

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.

How to create a MAAS CLI login shellscript

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 $PATH.

How to get help from the MAAS CLI

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.

How to log out of the MAAS CLI

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.