Approov CLI Installation

Setup

Requirements

You will need the following:

  • Approov account. You can sign up for a free trial. You will receive an email with the subject Approov Onboarding with activation information.
  • Approov tool that can be downloaded directly from here or via the Brew package manager.

Initializing the Approov CLI

All management of the Approov account is done using a Command Line Interface (CLI) tool available for Linux, MacOS and Windows and downloaded from here. Alternatively, for Linux and MacOS you can use Brew to install the Approov CLI. We suggest you use Brew if you already have it installed for other tools, otherwise use a direct download and installation.

Examples, showing how to use this tool, are provided throughout the documentation and a detailed reference for all the commands can be found in the Approov CLI Tool Reference.

The first step in using Approov is to install this tool on your system and then initialize it using the information provided in the Approov Onboarding email. If you are the account owner, initialization will grant account access with dev (development) and admin (administration) level roles available. Most operations can be carried out using the dev role, but the admin role is necessary for certain operations needing elevated privileges. If you received your Approov Onboarding email as a result of being added to an existing Approov account then you will be provided with a specific access role.

Follow the instructions to install the Approov CLI directly on Linux, MacOS or Windows. Once you have done this you can proceed with the remainder of these instructions. Use Brew Installation if desired instead for Linux or MacOS.

Initialize access to your Approov account using the information from the Approov Onboarding email. Copy and paste the instruction from the email, such as:

$ approov init your-account 542f15e4-6224-43c2-8e4b-015c5a5251cd
IMPORTANT: your recovery PIN is 287572 - make a note of this in case you ever need to recover your access
please provide a password (6 characters or more) to protect access
enter password:
confirm password:
approov access has been initialized
available role selection commands for account your-account:
  eval `approov role admin`
  eval `approov role dev`

If approov cannot be found then there has been an issue with the OS specific installation.

This operation grants access to your Approov account from your machine. The parameter your-account is the identifier of your allocated Approov account. The next parameter is a time limited onboarding code for your account.

You will normally be invited to choose a password for your access to Approov. If your onboarding included a dev role then this will be automatically selected for subsequent uses of the Approov CLI. You will be invited to type in the password again on first usage, and after every one hour session expires.

Note that you are also provided with a PIN number. You should make a note of this somewhere private and secure, it will be needed if you ever need to recover access to your account via email. The PIN provides an additional level of protection for your Approov account in case access to your email account is compromised.

You are now ready to start using Approov!

If you have been issued with older style Approov management tokens then you can import them to use with the latest CLI with access roles.

If a new version of the tool becomes available then an upgrade availability message will be shown when you invoke the tool. This will provide a link to the new version.

If you are setting up Approov on a new machine but you original onboarding email has expired, but you still have access to Approov on a different machine then you can resend onboading email using it to get a fresh onboarding email.

Installation on Linux

The download package includes a Linux subdirectory containing the approov executable. This should be placed in a directory that is on the $PATH. All examples in the documentation assume the approov tool is on the path and can be invoked directly.

Linux systems normally expect a bin directory at ~/bin or ~/.local/bin, and automatically include them in your $PATH. So you could, for instance, write the approov executable to ~/bin or ~/.local/bin, which should already be on your $PATH. If you prefer you can add it to /usr/local/bin instead, but you will need sudo permissions to copy it there.

Alternatively, you can create a new approov directory in your home directory (or other location of your choice) and then add this directory to your $PATH defined in the ~/.bashrc (or other, depending upon the shell used). For example the following can be added if the approov executable has been written to ~/approov-tool:

PATH=~/approov-tool:$PATH

When you install the Approov CLI tool in a custom location, such as ~/approov-tool, and after you add this location to the $PATH in your ~/.bashrc, you need to reload your shell source ~/.bashrc, otherwise invoking approov will fail.

Alternatively you can install the CLI using Brew.

Installation on MacOS

The download package includes a MacOSsubdirectory containing the approov executable. This should be placed in a directory that is on the $PATH. All examples in the documentation assume the approov tool is on the path and can be invoked directly. We suggest you write the approov executable to /usr/local/bin (or some other suitable folder) which should already be on your $PATH. You may need sudo permissions to copy it there.

If you update the version of approov in your $PATH then you might find it is killed by the kernel when you try and execute it. This is because the previous signature of the binary is retained in a kernel cache. If this occurs then reboot your machine to clear this problem.

Alternatively you can install the CLI using Brew.

Installation on Windows

The download package includes a Windows subdirectory containing the approov executable. This should be placed in a directory that is on the PATH. All examples in the documentation assume the approov tool is on the path and can be invoked directly.

Installation using Brew

Follow the Brew installation instructions if you do not already have it installed. To install the Approov CLI use:

brew update
brew install approov/cli/approov

If a new version of the Approov CLI becomes available then this will be shown in a message when you use the CLI. You can update with:

brew upgrade approov