The Basics

This is generally your first step when using the Metrix Sync CLI tool. It basically involves registering a valid Metrix API token with the Metrix Sync CLI tool so that it can use that token to authenticate with the Metrix API for subsequent operations. Additionaly, we recommend running our built-in update fetcher to ensure that you are always using the latest version of the Metrix Sync CLI tool.

With the above in mind, this help guide is broken into the following (ordered) sections:

  1. Fundamentals of using a CLI tool
  2. Update Check
  3. Creating an API Token for Metrix Sync CLI
  4. Registering the API Token with Metrix Sync CLI
  5. De-registering the API Token from Metrix Sync CLI (optional cleanup)

Subsections of The Basics

The Fundamentals

A Command Line Interface (CLI) tool allows you to interact with software using textual commands in a terminal or command prompt. The Metrix Sync CLI tool follows this paradigm, enabling you to perform various operations such as checking for updates, registering API tokens, and more, directly from your terminal.

Basic usage typically involves running the tool followed by a command and any options or arguments that the command requires. For example:

./metrix-sync.exe <command> [options]

Users may note the use of the ./ pattern, followed by the name of an executable (.exe) file. This is a common convention in command-line usage, and it means:

  • ./ indicates that the executable file is located in the current directory.
  • metrix-sync.exe is the name of the executable file being run.
Example

Assume you download the Metrix Sync CLI tool, and save it to a specific directory on your network - say, T:\tools\metrix.

You would need to ensure your terminal’s current working directory is set to the location where you saved the executable file. In this example, you would navigate to T:\tools\metrix before running the tool. Below, we show the use of the cd command to change the current working directory to the location of the executable file.

cd T:\tools\metrix

Next, lets assume you name the executable file metrix-sync.exe.

In this case (remembering that we are already in the directory where the executable file is located) you would run the tool from the terminal as follows:

./metrix-sync.exe

The above will launch the Metrix Sync CLI tool (without invoking any actual tools to run).

Update Checks

To perform an update check with the Metrix Sync CLI tool, simply run the following command:

./metrix-sync.exe update

The tool will call our secure Metrix update servers to check if you are running the latest stable version of the Metrix Sync CLI tool.

If any updates are available, the tool will return a download link for the latest version of the Metrix Sync CLI tool. Simply click the link (or copy and paste it to your browser) to download the new version. Copy/Move the downloaded executable file to the desired location on your system, and then run it as shown in the examples above.

API Token Generation

Creating an API token for the Metrix Sync CLI tool is a simple process that just requires you to generate it from the Metrix Asset Management system directly. Firstly, log in to your Metrix environment, and then:

  1. Navigate to the “My Profile” section by clicking the User Icon in the upper-right corner of the layout, and selecting “My Profile” from the dropdown menu.
  2. The subsequent page has a left-hand navigation menu. Click “API Keys” within this menu to see your options.
  3. You will see a list of any previous API Tokens you have generated*. To create a new one, simply enter a Name for the token (on the right-hand side form layout), and toggle on the following Scopes: a. Assets Read b. Users Read
  4. Click “Create API Key” to generate the new API key.
  5. Copy the generated API key and keep it in a secure location. You will not be able to view it again after this step.

* Important: If you no longer need (or recognise) an API Token, you should revoke it by clicking the “Delete” option next to that API Token in the list.

Registering an API Token with Metrix Sync CLI

To register an API token with the Metrix Sync CLI tool, use the following command:

./metrix-sync.exe register-token <your_api_token>

Replace <your_api_token> with your actual API token. This will allow the CLI tool to authenticate with the Metrix servers and perform authorised operations.

Note

The token is registered so that your user account can authenticate with the Metrix servers. That is, if another user logs onto the machine, they will need to register their own API token separately.

De-registering an API Token with Metrix Sync CLI

To de-register an API token with the Metrix Sync CLI tool, use the following command:

./metrix-sync.exe deregister-token

This will remove the registered API token from the Metrix Sync CLI tool, effectively de-authenticating your user account from the Metrix servers.