TransIP REST-API: using the CLI client

TransIP makes domain and VPS services available via a REST API. By using your own scripts, your website, application, or server sends a request directly to the TransIP systems.

One of the ways you can use the API is with our Command-Line Interface (CLI) client: TransIP-control (Tipctl).

Tipctl is a powerful tool with which you can easily access the API from your server's command line. All resources of the REST-API are available in Tipctl. In this article, we walk through the installation and configuration of the CLI client and show you how you can then use the CLI client.

Requirements

To use the REST-API command-line client the following software must be installed on your server:

• PHP 7.2 or newer
• PHP-json
• OpenSSL

PHP

For the installation of an Apache server with PHP, you can use our tutorials for installing Apache with PHP support. You're not required to install Apache if you don't want to host a website and can instead only use the steps that deal with PHP.

PHP-json + OpenSSL

Depending on your operating system, install the PHP-json extension and OpenSSL with:

CentOS:

sudo yum -y install php-json openssl

Ubuntu / Debian:

apt -y install php-json openssl

Installing and configuring the CLI client

There are two options for installing Tipctl: installation using Composer or downloading and nstalling the PHAR file. For the installation of Composer in Linux you can use this tutorial.

Installation using Composer

Step 1

The installation of Tipctl with Composer is done using the command:

composer global require transip/tipctl

Step 2

Now that the tipctl binary is available globally, make sure that your global vendor binaries directory is included in your environment $PATH variable. You can get the vendor binaries directory by using the following command:

composer global config bin-dir --absolute

The output will likely look something like /home/transip/.config/composer/ so the directory that needs to be added to your $PATH will then be /home/transip/.config/composer/vendor/bin. You can for example do so by opening the file:

nano ~/.bash_profile

In the opened file, adjust the PATH= line so the earlier bin directory is added there as well. The final result may look like this:

PATH=$PATH:$HOME/.local/bin:$HOME/bin:/home/transip/.config/composer/vendor/bin/

Save the changes and close the file ctrl + x > y > enter.

Step 3

Process the changes by using the command:

source ~/.bash_profile

You can then test Tipctl immediately using the command:

tipctl --version

Downloading and installing the PHAR file

Step 1

Retrieve the latest donload link for tipctl.phar from this page and download it with the command:

wget 

Replace 6.0.3 by the most current version number

Step 2

Make the file executable:

chmod +x ./tipctl.phar

Step 3

You can then test Tipctl using the commando:

./tipctl.phar --version

Step 4 - optional

Optionally you can configure an alias to be used for tipctl.phar. With an alias, you set up a shortcut for a command (or number of commands). Please note that this only works from command-line and not from within shell-scripts, cronjobs, etc.

Open the file ~ / .bashrc (the file with the user's shell configuration profile):

nano ~/.bashrc

Step 5 - optional

Depending on your operating system you can see whether a relatively empty (CentOS) or filled (Debian, Ubuntu) file. Add the following code to the bottom of the file:

alias tipctl='~/bin/tipctl.phar'

Replace the directory with the location on your VPS in which the CLI client is located. Then, close the file and save the changes (ctrl + x > y > enter).

Step 6 - optional

The changes are processed after a reboot or use the following command to process the changes immediately:

source ~/.bashrc

The initial setup

Before you can use Tipctl, you'll need to run the setup process once to link your TransIP account to Tipctl.

Step 1

Start the setup using:

tipctl setup

Step 2

You're shown the following steps one by one:

Enter the RestAPI url [https://api.transip.nl/v6]:
Enter your TransIP Username []: jetransipaccount
Use IP Whitelisting? [Yes]:
Enter your RestAPI Private Key:
-----BEGIN PRIVATE KEY-----MIIEvgIkWyaxuFA977cDw6Kn-----END PRIVATE KEY-----
Checking API connection to endpoint 'https://api.transip.nl/v6'

API connection successful
Config file saved in /home/transip/.config/transip-api/cli-config.json

• Enter the RestAPI url: Press 'Enter' to automatically use the URL between the brackets.
• Enter your TransIP Username: Provide the name of your TransIP account.
• Use IP Whitelisting: Press 'Enter' to use whitelisting (default value). Type 'no' if you haven't enabled whitelisting for the API in your TransIP control panel.
• Enter your RestAPI Private Key: This is the private key which you generate on the API page in the TransIP control panel, see our general API guide.

Using the CLI client

Now that the alias has been set, you can call the CLI client with the command:

tipctl

You will now see an overview of all available commands. Are you looking for a specific option, such as commands that affect DNS? You can use 'grep' to specify the output:

tipctl | grep dns

You can easily execute most available commands with the syntax:

tipctl product:command

For example:

tipctl vps:start

Do you want to know which variables you must provide? Then, add -h to the command:

tipctl -h vps:start

The output of this will look like this:

Description:
  Start a Vps

Usage:
  vps:start [options] [--] <VpsName>

Arguments:
  VpsName                The name of the vps

Options:
      --format[=FORMAT]  The output format `txt`, `yaml` or `json` [default: "json"]
  -h, --help             Display this help message
  -q, --quiet            Do not output any message
  -V, --version          Display this application version
      --ansi             Force ANSI output
      --no-ansi          Disable ANSI output
  -n, --no-interaction   Do not ask any interactive question
  -v|vv|vvv, --verbose   Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  Provide a Vps name to start

Security considerations

The command-line client is a powerful tool for using our REST-API. The installation is very easy, and the client is precompiled. You only have to execute one command to get an overview of all available functions within the REST API.

With the CLI client, it no longer matters which programming language you use. As long as the language you use can  execute a shell command from the server hosting your application, you can use the client.

We recommend to only use Tipctl for troubleshooting and managing your account directly through command-line however. For actual implementations we recommend to instead use the available options for PHP or Curl for example.

If you do want to call upon Tipctl from within your application, it's important to keep in mind the following security risk: If you allow a command to be modified via user input, malicious commands can be added. Therefore, make sure that you always escaped (placed in brackets) any user input, so that commands are read as a string and not executed as a command.

This concludes our tutorial on how to use our API CLI client Tipctl. Should you have any questions left regarding this article, do not hesitate to contact our support department. You can reach them via the ‘Contact Us’ button at the bottom of this page.