How To Set Up and Use The Liquid Web CLI Interface  

What Is the Liquid Web CLI Interface?

This is the official command-line interface for the Liquid Web API. CLI stands for the “command-line interface” which is used for interacting with multiple Liquid Web services via the Liquid Web’s Public API.  

Why Should I Use a CLI Utility?

The answer is simple, to better harness the power of the Liquid Web API to automate and manage our Liquid Web Cloud resources. This option opens up endless possibilities, from the development stage through testing and deployment of our scaled project into a production environment. 

Preflight Check

First, we need to ensure we have created an API user. We will use the info from the article Creating an API User in Manage, to accomplish this step. There are several installation methods, so we should select the installation method that best fits our platform and skill level. 

The installation for MacOS and Windows requires a prebuilt binary approach. We also have the option to install via .rpm and .deb packages. This method is supported for both the RedHat and Debian based Linux distributions.  

Installation Methods 

Getting started with The Liquid Web CLI interface is reasonably straightforward. The preferred installation method this article will follow is to visit the Liquid Web GitHub CLI release page to obtain the most recent prebuilt binary for our platform. As of today, the latest release version of the Liquid Web CLI is 0.6.8 

Prebuilt Binaries

MacOS 

Step 1. Open a terminal, or using Finder, open /Applications/Utilities/Terminal.app

Step 2. Run the following commands to create a directory for liquidweb-cli and then cd to it.

mkdir liquidweb-cli
cd liquidweb-cli

Step 3. Next, we will use the wget command to download the most recent release version.

wget https://github.com/liquidweb/liquidweb-cli/releases/download/v0.6.8/lw_0.6.8_Darwin_x86_64.tar.gz

Step 4. Then, extract the tar.gz file into the current directory by running the following command.

gunzip -c lw_0.6.8_Darwin_x86_64.tar.gz| tar xopf -

Step 5. Finally, we will want to add the liquidweb-cli directory to our PATH.

export "PATH=$(pwd):$PATH"

Step 6. We can verify the installation worked using the which command. 

which lw
/Users/admin/liquidweb-cli/lw

Additionally, we should add the directory to our path in our .bashrc or .bash_profile, so the directory is added to our PATH every time we open a new terminal session. 

export PATH="/Users/admin/liquidweb-cli:$PATH"

Windows

Step 1. Download the latest tar.gz file from GitHub. 

Step 2. Extract the lw_0.6.8_Windows_x86_64.tar.gz file to a chosen directory. 
**Note: We used 7Zip which required us to unzip the .tar file, and then the .gz file**

Step 3. Press Windows+R to open the “Run” box and then type in “cmd” and then click “OK” to open a regular terminal command prompt. After we open a terminal, change to the directory where we extracted the liquidweb-cli files. 

cd c:\path\to\file\lw.exe

Step 4. Browse to the folder where the lw.exe file was extracted and run the lw.exe file with one of the following commands or flags to initiate the CLI tool. Running the lw.exe command by itself shows the following output.

C:\lw_0.6.8_Windows_x86_64.tar\lw_0.6.8_Windows_x86_64>lw.exe
CLI interface for LiquidWeb.

Command line interface for interacting with LiquidWeb services via
LiquidWeb's Public API.

If this is your first time running, you will need to setup at least
one auth context. An auth context contains authentication data for
accessing your LiquidWeb account. As such one auth context represents
one LiquidWeb account. You can have multiple auth contexts defined.

To setup your first auth context, you run 'auth init'. For further
information on auth contexts, be sure to checkout 'help auth' for a
list of capabilities.

As always, consult the various subcommands for specific features and
capabilities.

Usage:
  lw [command]

Available Commands:
  auth        authentication actions
  cloud       Interact with LiquidWeb's Cloud platform.
  help        Help about any command
  network     network actions
  plan        Process YAML plan file
  version     show build information

Flags:
--config string      -config file (default is $HOME/.liquidweb-cli.yaml)
-h, --help           -help for lw
--use-context string -forces current context, without persisting the context change

Use "lw [command] --help" for more information about a command.
subcommand is required

Prebuilt RPM/DEB Packages

If we are running a RedHat or Debian based Linux distribution, we can install the Liquid Web CLI tool via the prebuilt rpm/deb packages also found on our releases page.

To install on .rpm based Linux distributions,  run the following commands.

wget https://github.com/liquidweb/liquidweb-cli/releases/download/v0.6.8/lw_0.6.8_linux_x86_64.rpm
rpm -i ./lw_0.6.8_linux_x86_64.rpm

To install on .deb based distributions, run the following commands.

wget https://github.com/liquidweb/liquidweb-cli/releases/download/v0.6.8/lw_0.6.8_linux_x86_64.deb 
rpm -i ./lw_0.6.8_linux_x86_64.rpm

Compiling From Source

Advanced users can install the Liquid Web CLI tool by cloning the git repository by running the following git command.

git clone https://github.com/liquidweb/liquidweb-cli.git

Then, build the Liquid Web CLI tool from source by running the following command.

cd liquidweb-cli
make build 

The resulting program will reside at ./_exe/lw. 

We can also build and install the lw-cli tool onto our system using either the 

go install 

or 

make install 

method from the extracted folder. The default installation uses the make command with no arguments.

Once we have installed the lw cli utility using one of the outlined methods above, we are ready to move on setting up authentication contexts, as described in the next section.

Configuring Auth Contexts

If this is the first time running lw, we will need to set up at least one authentication context or “auth” context. An auth context contains the authentication data required for accessing our Liquid Web account. Using the following commands, we can add, remove, or update an auth context.

help auth add-context --context helpfulhuman --username helpful --password 

help auth remove-context --context helpfulhuman --username helpful --password  

help auth update-context --context helpfulhuman --username helpful --password 

Create an Auth Context

To set up our first auth context, run and type ‘yes’ and hit Enter when prompted.

lw auth init                                         
no config
Warning: This will delete all auth contexts. Continue (yes/[no])?:  >

Enter a name to define our auth context when prompted:

Name this context:  >

Next, we will enter our Liquid Web API username and then hit enter.

LiquidWeb username:

Then, enter the password for the API user.
**Please Note: The password characters are not displayed on screen**

LiquidWeb password:

Finally, to confirm the context, type yes, and hit enter. (For this tutorial, when prompted to add another context type no and hit enter.)

Name this context:  > HelpfulH
LiquidWeb username:  > helpfulh
LiquidWeb password:
Make current context? ([yes]/no) > yes
Add another context? (yes/[no]):  > no

For further information on auth contexts, be sure to check out ‘lw help auth’ command for a full list of capabilities.

Add New Auth Contexts

To add a context for a different account or different API user, run this command.

lw auth add-context --context ""HelpfulH2" --username helpful2 --password "yPK4VgQb53tQ"

This command creates a new auth context named “HelpfulH2” using the API username “helpful2” and password “iVML2ElKTYal.”

Switch Auth Contexts

Having multiple contexts may require us to switch between them if we need to interact with them. To define a list of contexts, we can run the following command.

lw auth get-contexts

In this example, we have one context named “HelpfulH” and one called “HelpfulH2”. Our current context is called “HelpfulH.”

Context: HelpfulH2
 Username: helpful2
 API URL: https://api.liquidweb.com
 Insecure: false
 Timeout: 90

Context: HelpfulH
 Username: helpful
 API URL: https://api.liquidweb.com
 Insecure: false
 Timeout: 90
Current context: [HelpfulH]

If we want to change contexts to interact with the HelfpulH2 resource, we can run the following command, which specifies the context with which we wish to interact. For example:

lw auth use-context HelpfulH2
context changed to [HelpfulH2]

Modify Auth Contexts

Luckily, the lw CLI makes that easy. For example, the following command would update the username and password for the context named “HelpfulH.”

lw auth update-context --context HelpfulH --username helpful --password SIRxd7bIVA31

Remove Auth Contexts 

If we need to remove an auth context, we will run the following command (replacing “HelpfulH2” with the name of the context we wish to remove.) 

lw auth remove-context --context HelpfulH2

Liquid Web CLI Tool Usage 

The Liquid Web CLI utility interacts with our Cloud resources in multiple ways. It obtains information about our servers and services, scales resources in simple or complex environments, allows us to create new resources such as Cloud VPS servers, Private Cloud servers, as well as Cloud Dedicated servers on the fly. It can be used to manage both public and private networking, and interact with various cloud services such as backup services, server images, and storage. 

Additionally, advanced users can utilize a “plan” file. A plan file is a predefined .yaml file with optional template variables used to repeat specific tasks. (A plan file would be comparable to a cookbook in Chef or a manifest file in Puppet.) This type of option can be particularly useful in development, testing, deployment, and scaling production environments. 

Basic Command Usage

The lw tool can interact with individual Liquid Web Cloud features by invoking commands and often with one or more options that specify particular settings. Commands are broken down into the following categories:

•   auth        authentication actions
•   cloud       Interact with LiquidWeb’s Cloud platform.
•   help        Help about any command
•   network     network actions
•   plan        Process YAML plan file
•   version     show build information

List Cloud Servers

lw cloud server list 

Check Cloud Servers Status

lw cloud server status 

List Available Options

To create new servers or interact with existing resources, we will need to determine the options available to us. If we run the following command, we will see that the options are broken down into three basic categories

lw cloud server options

Regions/Zones

Templates: (cloud server images provided by LiquidWeb)

Config-id’s: (a config-id represents a type of server, for example, config-id 1234 might represent a configuration with the following hardware specifications: 
   16 GB RAM
   300 GB Disk
   8 vCPUs 

• Zones are regional locations where Cloud resources are created and which configs are available.
• Template provides a list of models defining the available OS and software installed on your VPS. For example, CentOS & InterWorx.
• Config-id's define the server’s resources, like disk space and memory.

If we need to get a list of the available zones where we can create a Cloud VPS, we will run the following command.

lw cloud server options --zones

The output should provide us with a list of the available Zones and their ID numbers to create additional cloud resources.

Working region [US West (id: 2)] zone [Zone A (id: 15)]
  zones:
    Region: US West (id: 2) Zone: Zone A (id: 15)
Working region [EU West (id: 3)] zone [Zone A (id: 26)]
  zones:
    Region: EU West (id: 3) Zone: Zone A (id: 26)
Working region [US Central (id: 1)] zone [Zone C (id: 27)]
  zones:
    Region: US Central (id: 1) Zone: Zone C (id: 27)
Working region [US Central (id: 1)] zone [Zone B (id: 12)]
  zones:
    Region: US Central (id: 1) Zone: Zone B (id: 12)

To obtain a list of OS templates available to create a Cloud VPS, we would run the following command.

lw cloud server options --templates

This output will give us a list of the available OS templates and their corresponding ID numbers. For example:

name: CENTOS_7_INTERWORX
description: CentOS 7 64-bit with Interworx Fully-managed
manage_level: full
os: LinuxCentOS
id: 270

To obtain a list of the available server configs needed to create a Cloud VPS, we would run the following command.

lw cloud server options --configs

The output will provide us a list of available configs and their corresponding ID numbers. For example:

config-id: 1437
  description: 16GB - SSD
  active: 1
  available: 1
  category: ssd
  disk: 200
  memory: 16000
  vcpu: 8

Create Cloud Servers

Now that we are familiar with what options are available, we are ready to use the lw tool to create a new cloud server. For example, the following command will create a Cloud VPS server with Centos 7 using the Interworx control panel applying config id 1437,  in the US Central region in Zone C id:27

lw cloud server create --config-id 1437 --zone 27 --template CENTOS_7_INTERWORX 

We will receive output similar to the following informing us of how to check the status of your server create command option.

lw cloud server status --uniq-id MJCXSC                                                                                        
UniqId: MJCXSC
 domain: 2ch2.qoe0xqi7i6.io
 status: Building
 detailed status: Waiting for disk synchronization
 running: [{CurrentStep:216 DetailedStatus:Waiting for disk synchronization Name:Create Server Status:Building}]
 progress: 0

Destroy Cloud Servers

Not only can you create services using the lw cli utility, but you can also destroy them. For example, to terminate the server we created in the previous example, we would run the following command.

lw cloud server destroy --uniq-id MJCXSC       

We will then be asked to confirm the server deletion.
**Tip: Avoid future confirmations by passing the --force flag**

This is a destructive operation. Continue (yes/[no])?:

Resize Cloud Server

Another benefit of using a utility like this is the ability to scale your resources quickly. For example, if our project is launching soon, and we need more resources temporarily for our production server to handle the expected traffic, we can resize it easily! We just specify the uniq ID of the server we wish to resize and the desired config. 

lw cloud server resize --config-id 1536 --uniq-id MJCXSC

Simple Yet Powerful

As you can see, any environment from the simplest to the most complex can benefit from using this utility. We can spin up servers for development and testing to deploying and scaling large production environments using plan files and scaling production environments to handle traffic as needed. The official command-line interface for Liquid Web API can supercharge your workflow and empower you to quickly and efficiently automate and interact with all your hosting resources. 

Contribute

If you wish to participate by contributing to this project, the official command-line interface for the LiquidWeb API is written in Go and open-sourced on GitHub under the Apache 2.0 License. Feel free to contact the maintainers there.

We pride ourselves on being The Most Helpful Humans In Hosting™!

Our talented Support Teams are full of experienced Linux technicians and System administrators who have an intimate knowledge of multiple web hosting technologies, especially those discussed in this article. We are always available to assist with any issues related to this article, 24 hours a day, 7 days a week 365 days a year.

If you are a Fully Managed VPS server, Cloud Dedicated, VMWare Private Cloud, Private Parent server, Dedicated Server, or Managed Cloud server owner and you are uncomfortable with performing any of the steps outlined, we can be reached via phone @800.580.4985, a chat or support ticket to assisting you with this process.