Install the Grey Matter CLI

This guide will help you install and set up the Grey Matter CLI.

The Grey Matter Command Line Interface (CLI) is a configuration tool for the Grey Matter Control API. Leveraging the Control API, the CLI mainly performs dynamic configuration of the Fabric mesh.

Q: How do the CLI and the Control API interact?

A: The CLI manipulates configuration objects registered with the control plane to control the behavior of the sidecars making up the mesh. Learn more about these mesh objects if you haven't already.


To complete this tutorial, you’ll need an understanding of, and local access to the following environments and tools:

  • Unix Shell (or equivalent)

  • A running Grey Matter Fabric mesh to interact with

Step 1: Download and Install the greymatter CLI

The greymatter CLI is a binary written in Go. There are two ways to install it:

A. use gmenv, a manager for installing and setting different greymatter versions B. download the binary manually from our release pages

We recommend using gmenv because it allows for easier versioning against different Grey Matter environments.

  • Install gmenv following the README

  • Once installed, install the latest version of greymatter using gmenv install. This will download and install the latest version of the greymatter CLI:

$ gmenv install
No credentials for Grey Matter found. Prompting for user credentials.
gmenv needs your Grey Matter LDAP credentials to retrieve Grey Matter from Nexus.
Your information will be temporarily stored in $HOME/.gmenv/credentials
Enter your Grey Matter LDAP username:
Enter your Grey Matter LDAP password: Installing Grey Matter v1.2.1
Downloading release tarball from
Installation of greymatter v1.2.1 successful

To make this your default version, run gmenv use 1.2.1

Option B: Install the greymatter binary manually

Web UI

Retrieve the latest release directly or visit Grey Matter's Nexus Repository to browse all released versions of the CLI. When prompted, enter the username and password associated with your Grey Matter account.

The greymatter CLI can be found in the raw section under the release/gm-cli tree direct link. If you need binaries for a different platform, or for a different version, they can all be found on our Nexus repo.


Any artifact in nexus can also be downloaded with a terminal. The below command demonstrates how to do this with curl. Before executing, replace -u with your username, and make sure the desired artifact is specified.

curl -u > greymatter-v1.2.1.tar.gz

greymatter is distributed as a precompiled binary. The installation requires two steps:

  1. Unpacking the tarball

  2. Moving the greymatter binary onto your system's PATH

Untar the Binary

Once you've downloaded the Grey Matter binary, unzip it.

tar -xvzf greymatter-v1.2.1.tar.gz

Move the Binary into Your $PATH

Next, move the binary for your operating system into your $PATH e.g.:

sudo mv ./greymatter.linux /usr/bin/greymatter

On a Mac?

On a Mac there is SIP mode which won't let you move the binary into your $PATH. Follow these instructions to disable rootless mode:

  1. Reboot into recovery mode (reboot and hold down Cmd-R)

  2. Open a terminal

  3. Use this command: csrutil disable

  4. Reboot and run the command that worked prior to El Capitan

  5. When you're done, it is highly recommended that you re-enable SIP by following the same steps, but using csrutil enable in step 3.

Make sure to rename your binary for your operating system to just greymatter when moving the artifact into your $PATH

Step 2: Configure Your Environment for Grey Matter

In addition to downloading and installing the greymatter CLI, you'll need to set the necessary environment variables or command line flags so that you can talk to a deployed Grey Matter API. As each deployment is different, the specific endpoint and security context will be different, so make sure to verify your settings against the deployed environment.

The full configuration and usage of the CLI can be found in the support pages or by running greymatter --help, but some quick examples are shown here.

Configuration via Flags

Configuration options can be set by CLI flags with each use.

greymatter create --api.prefix=/services/control-api/latest --api.ssl=true route < route.json

Configuration via Environment Variable

Configuration can also be set via the environment to avoid repeating verbose commands like the above. Any of the CLI flags will be parsed from the environment with underscore-delimited environment variables prefixed with "GREYMATTER_". For example, "--some-flag" becomes "GREYMATTER_SOME_FLAG". Command-line flags will still take precedence over environment variables.

NOTE: If you've used our quickstart then your GREYMATTER_API_PREFIX will be /services/control-api/latest like shown below.

export GREYMATTER_API_PREFIX='/services/control-api/latest'
export GREYMATTER_API_SSL='true'
export GREYMATTER_API_SSLCERT="/path/to/my.crt"
export GREYMATTER_API_SSLKEY="/path/to/my.key"

Step 3: Test Installation

Run a quick test of the binary with the following command to verify a successful installation.

$ greymatter --version
Grey Matter CLI
Command Name: greymatter
Version: v1.2.1
Branch: release-1.2
Commit: cccfd74
Built: Sun, 29 Mar 2020 20:52:30 UTC by justincely
Grey Matter Control API
Version: v1.2.0-dev

Step 4: Connect to the Grey Matter Control API

This section requires a running instance of the Grey Matter Control API server. Your GREYMATTER_API_HOSTand many other configuration options will change based upon where the Control API service is deployed.

List Zone

Use greymatter list zone \ with the following keys and certs to connect to the Grey Matter Control API.

$ greymatter list zone
"zone_key": "zone-default-zone",
"name": "default-zone",
"checksum": "6883b95eb2dbd05e15c54fcd0e5414bcb5a6aee1d3b91ab2d1c6493e4945ff74"

The returned Zone indicates that the connection was successful, and you've been able to inspect the Fabric Mesh.


Need help with your installation?

Create an account at Grey Matter Support to reach our team.