Overview

The MetaRouter CLI provides additional tools that will help you manage MetaRouter. You can find instructions for these tools below:

• Event Debugger
• Playbook Testing
• Generating & Checking TLS Certificates
• Transformation Library

The rest of this guide will walk you through the installation steps required to access CLI tools.

Before You Begin

System Requirements

Ensure that you have access to a Linux or Mac terminal. If you use Windows, you can use Windows Subsystem for Linux (WSL).

Windows Users

Windows users will need to install Ubuntu in order to access CLI tools. You can do by following these instructions:

1. Install Terminal Preview.
2. Search for the “Terminal Preview” app within your file. Right-click the file and select “Run as Administrator.”
3. In the new tab, type this command: wsl --install -d ubuntu
4. Reboot your computer.
5. Enter a username and password that you will use to login to Ubuntu.
6. Repeat Step #2.
7. To the right of the Powershell tab, click the downward caret symbol. Select “Ubuntu.”
   1. (Optional) Set Ubuntu as your default profile. In the same menu, click “Settings” and set Ubuntu as your default profile.
8. Type this command: sudo apt update . Hit enter. Type the password you set in Step 5 and hit enter.
9. Type sudo apt upgrade and hit enter.

💡

It is strongly encouraged that you also enable “automatic” time updates for your local machine to avoid OAuth Token mismatch issues. To do this:

1. Press the Windows key to open the Start menu search.
2. Type “services” and open the Services utility.
3. Scroll down to Windows Time and right-click it. Select Properties
4. In the Windows Time Properties window, set Startup type to Automatic. Then click Start to ensure the service is running, followed by OK to save your changes.

Mac Users

The Mac Terminal comes preinstalled on Mac devices. Mac users can continue on to the next section.

Install Homebrew

MetaRouter uses Homebrew to install the CLI tool set on your local environment. Follow these instructions to install it. Do not skip any setup steps as this may prevent accessing CLI tools.

After successfully installing Homebrew, run the following command in your terminal to add our custom “tap”. This will allow your computer to access and install the MetaRouter CLI install files.

brew tap --force-auto-update metarouter/tools https://gitlab.com/metarouter/tools.git && \
brew install metarouter/tools/cli

User Access to enterprise.metarouter.io

Ensure that you have access to an organization on enterprise.metarouter.io. Your organization will also need a cluster setup to ensure that you can access data within the CLI tools.

Getting Started with the MetaRouter CLI

Now that you have the MetaRouter CLI installed, you can begin entering commands to navigate between your MetaRouter resources. The MetaRouter CLI interacts with individual clusters that the MetaRouter is installed upon. This tool allows you to interact with clusters to view playbooks, pipelines, and event metadata as it flows through the platform.

Here are some helpful commands to help you get started:

This is not a complete list of commands available in the CLI. Additional commands and usage can be discovered using the built-in contextual help

Getting Help

passing the --help flag will provide detailed usage information for the command being used, or list commands, common usage, etc. if no command was specified.

$ control login --help
Logs into the CLI client

Usage:
  control login [flags]

Flags:
  -e, --env string   login to specific environment: production, staging, dev, or review (default "production")
  -h, --help         help for login

Logging In

1. Login into enterprise.metarouter.io on your browser. If you are a member of multiple Organizations, navigate to the top-right Organization drop-down menu and select the Organization you’d like access with the CLI. The CLI can only access one Organization at a time.
2. Run control login to start the login prompt. Within the pop-up window, login if necessary.
3. The CLI will present an alphanumeric string. Verify this matches the string that shows in the pop-up window and click Confirm.

Selecting Your Cluster

You will need to designate which cluster you would like to access. Each cluster will correspond to a number. Type the number assigned to the cluster you’d like to access, and hit enter. You will now be able to access the Debugger or Forge Playbook Testing for that cluster.

Switching Between Clusters

Use the control config clusters command to display a list of clusters you have access to. Use the corresponding numerical input to select the new cluster you wish to connect to.

If you do not see the cluster(s) you are hoping to access, ensure you have selected the correct Organization within your browser. You will need to run control login again and repeat the prior login steps to get access to your cluster if you had the wrong Organization selected.

Common Errors

When fetching data using this tool, many elements come into play. If an error occurs, it will be specified in the first line that the tool returns

Updating

Changes are made rather frequently to the CLI (impacting both control and forge tools). So, the tool will check for new versions when it runs. The tool’s output will include an alert to upgrade when an upgrade is available.

$ control get events
WARNING: Your cli version (v4.37.1) is out of date. Please update to v4.49.0.
Try this command:
> control update
Or visit https://gitlab.com/metarouter/tools for instructions.

When this occurs, simply run control update, and enter ‘y’ at the prompt

Logging Out

Use the control reset command to logout and fully reset your local environment. When running this command, you will likely encounter an error that reads: ERROR: check cli version: SQL logic error: no such table: semvers (1). This is expected behavior. You can still proceed with performing other CLI actions if necessary.