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.
To use the REST-API command-line client the following software must be installed on your server:
- PHP 7.2 or newer
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:
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
The installation of Tipctl with Composer is done using the command:
composer global require transip/tipctl
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:
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:
Save the changes and close the file ctrl + x > y > enter.
Process the changes by using the command:
You can then test Tipctl immediately using the command:
Downloading and installing the PHAR file
Retrieve the latest donload link for tipctl.phar from this page and download it with the command:
Replace 6.0.3 by the most current version number
Make the file executable:
chmod +x ./tipctl.phar
You can then test Tipctl using the commando:
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):
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:
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:
The initial setup
Before you can use Tipctl, you'll need to run the setup process once to link your TransIP account to Tipctl.
Start the setup using:
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
All available commands can be found in the /src/Command directory
Now that the alias has been set, you can call the CLI client with the command:
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:
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
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 ‘ContactUs’ button at the bottom of this page.
If you want to discuss this article with other users, please leave a message under 'Comments'.