# Install the Grey Matter CLI

![](https://2512473607-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LsNFVozLgvw3NDMzxBg%2F-LyUdvQlwMWNOF82kqyb%2F-LyUgIkFwCh35eNgKZ3j%2FCLI%404x.png?alt=media\&token=06801f7b-2295-487b-9b68-82fa3c14be5b)

The **Grey Matter Command Line Interface (CLI)** is a configuration tool for Grey Matter. Leveraging the [Grey Matter Control API](https://greymatter.gitbook.io/grey-matter-documentation/usage/fabric/api), the CLI mainly performs dynamic configuration of the Fabric mesh.

{% hint style="success" %}
**Q: How do the CLI and the Grey Matter 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](https://greymatter.gitbook.io/grey-matter-documentation/usage/fabric/api) if you haven't already.
{% endhint %}

## Prerequisites

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

* Unix Shell (or equivalent)
* A [Grey Matter account](https://support.greymatter.io)

## Step 1: Download and Install the `greymatter` CLI

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

1. use [`gmenv`](https://github.com/greymatter-io/gmenv), a manager for installing and setting different `greymatter` versions
2. download the binary manually from our release pages

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

### Option A (recommended): Use `gmenv`

* [Install gmenv](https://github.com/greymatter-io/gmenv#installation) using homebrew or manually following the README
* [Configure it with your Grey Matter credentials](https://github.com/greymatter-io/gmenv#credentials) (the email and password used to access [Grey Matter's Nexus Repository](https://nexus.greymatter.io/)). For ease of use, it is recommended to [use a credentials file](https://github.com/greymatter-io/gmenv#credentials-file).
* Run `gmenv install 1.4.2` to install the latest version of the CLI. You should see:

  ```bash
  Installation of greymatter v1.4.2 successful. To make this your default version, run 'gmenv use 1.4.2'
  ```
* Run `gmenv use 1.4.2` to set this as your version.

  ```bash
  Switching default version to v1.4.2
  Switching completed
  ```

### Option B: Install the `greymatter` binary manually

Retrieve the [latest release directly](https://nexus.greymatter.io/repository/raw/release/gm-cli/greymatter-v1.4.2.tar.gz) or visit Grey Matter's [Nexus Repository](https://nexus.greymatter.io/#browse/browse:raw:release%2Fgm-cli) to browse all released versions of the CLI. When prompted, enter the username and password associated with your Grey Matter account.

Alternatively, 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 user.name@organization.com` with your username, and make sure the desired artifact is specified.

```bash
curl https://nexus.greymatter.io/repository/raw/release/gm-cli/greymatter-v1.4.2.tar.gz -u user.name@organization.com > greymatter-v1.4.2.tar.gz
```

`greymatter` is distributed as a precompiled binary. Once you have downloaded the desired release, install it with the following steps:

1. Unpack the tarball

   ```bash
   tar -xvzf greymatter-v1.4.2.tar.gz
   ```

   You will see the binaries:

   ```bash
   x ./greymatter.linux
   x ./greymatter.exe
   x ./greymatter.osx
   ...
   ```
2. Move the `greymatter` binary for your operator onto your system's `PATH` with name `greymatter`:

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

{% hint style="success" %}
**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.
   {% endhint %}

{% hint style="danger" %}
Make sure to ***rename your binary*** for your operating system to just `greymatter` when moving the artifact into your `$PATH`
{% endhint %}

## Step 2: 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.4.2
 Branch:                        release-1.4
 Commit:                        455e5fc
 Built:                         Wed, 08 Jul 2020 18:47:07 UTC by justincely
Grey Matter Control API
 Version:                       v1.4.2-dev
```

If you don't see this response, verify that the `greymatter` binary is on your `PATH`.

## Step 3: Configure Your Environment for Grey Matter

Once the CLI has been downloaded and installed, it will need to be configured for your Grey Matter installation to communicate with the Grey Matter Control API. If you don't yet have an existing Grey Matter installation, get started with the [Quickstart Installation Guide](https://greymatter.gitbook.io/grey-matter-documentation/guides/installation-kubernetes), and you will be able to configure the Grey Matter CLI and complete [step 4](#step-4-test-connection-to-the-grey-matter-control-api) once it is up.

If you have an existing deployment running, configure the CLI by setting the following environment variables in your terminal. Note that 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.

```bash
export GREYMATTER_API_HOST=services.greymatter.io:443
export GREYMATTER_API_PREFIX=/services/control-api/latest
export GREYMATTER_API_SSL=true
export GREYMATTER_API_INSECURE=true
export GREYMATTER_API_SSLCERT=/path/to/my.crt
export GREYMATTER_API_SSLKEY=/path/to/my.key
export EDITOR=vim # or your preferred editor
```

It is recommended to use an absolute path for your `GREYMATTER_API_SSLCERT` and `GREYMATTER_API_SSLKEY` variables.

> NOTE: If you've used our [quickstart guide](https://greymatter.gitbook.io/grey-matter-documentation/guides/installation-kubernetes) - see the [configure the CLI](https://greymatter.gitbook.io/grey-matter-documentation/installation-kubernetes#7-configure-the-cli) section for the specific configurations.

The full configuration and usage of the CLI can be found in the [support](https://greymatter.gitbook.io/grey-matter-documentation/usage/fabric/cli) pages or by running `greymatter --help`, but some quick examples are shown here.

Configuration options can also be set by CLI flags with each use. These flags will take precedence over the set environment variables.

```
  greymatter create --api.host=services.greymatter.io:443 --api.prefix=/services/control-api/latest --api.ssl=true route < route.json
```

## Step 4: Test connection to the Grey Matter Control API

{% hint style="warning" %}
This section requires a running instance of the **Grey Matter Control API server**. Your `GREYMATTER_API_HOST`and many other configuration options will change based upon where the Control API service is deployed.
{% endhint %}

### 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. You can now interact with your Grey Matter installation using the CLI!

If you see a connection refused error, your configuration is likely wrong. Check the values you have configured by running `greymatter` with no command, the options configured from the environment will be listed at the bottom of the output.

## Questions?

{% hint style="success" %}
**Need help with your installation?**

Create an account at [Grey Matter Support](https://support.greymatter.io/support/home) to reach our team.
{% endhint %}
