# Set up the CLI

![](https://1676458320-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 the Grey Matter Control API. Leveraging the Control API, the CLI mainly performs dynamic configuration of the Fabric mesh.

{% hint style="success" %}
**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](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/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)
* A running Grey Matter Fabric mesh to interact with

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

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

1. Use `gmenv`, a manager for installing and setting different `greymatter` versions
2. Download the binary manually from our [published releases](https://nexus.greymatter.io/#browse/browse:raw:release%2Fgm-cli)

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

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

1. Install [gmenv](https://github.com/greymatter-io/gmenv): a. On a Mac, using brew:

   ```bash
      brew install greymatter-io/homebrew-greymatter/gmenv
   ```

   b. Alteratively, you can follow [these steps](https://github.com/greymatter-io/gmenv#manual):

   a. Check out gmenv into any path (here is `${HOME}/.gmenv`)

   ```bash
        git clone https://github.com/greymatter-io/gmenv.git ~/.gmenv
   ```

   b. Add \~/.gmenv/bin to your `$PATH` any way you like

   ```bash
        echo 'export PATH="$HOME/.gmenv/bin:$PATH"' >> ~/.bash_profile
        source ~/.bash_profile
   ```
2. Once installed, list the versions of `greymatter` available

   ```bash
      gmenv list-remote
   ```

   > Note: If you haven't used `gmenv` before, you will be prompted for your Grey Matter LDAP username and password.
3. Install the latest version of `greymatter` using `gmenv install <version>`. This will download and install the latest version of the `greymatter` CLI:

   ```bash
    gmenv install <version>
   ```
4. Tell `gmenv` to use the newly downloaded version of the Grey Matter CLI

   ```bash
    gmenv use <version>
   ```
5. Verify the correct version of `greymatter` was installed

   ```bash
    greymatter version
   ```

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

#### Web UI

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

{% hint style="info" %}
The `greymatter` CLI can be found in the `raw-hosted` section under the `greymatter/gm-cli` tree [direct link](https://nexus.greymatter.io/#browse/browse:raw:release%2Fgm-cli). If you need binaries for a different platform, or for a different version, they can all be found on our [Nexus repo](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/greymatter-nexus).
{% endhint %}

#### Terminal

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.2.1.tar.gz
-u user.name@organization.com > 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.

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

```bash
./greymatter.linux
./greymatter.exe
./greymatter.osx
```

#### Move the Binary into Your $PATH

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

```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 Command + 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: 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](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/cli) 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.host=services.greymatter.io:443
--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 [Install on Kubernetes guide](https://greymatter.gitbook.io/grey-matter-documentation/1.3/installation/installation-kubernetes), then your `GREYMATTER_API_PREFIX` will be `/services/control-api/latest` like shown below.

```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"
```

### Configuration via Configuration File

Configuration can also be set via a configuration file using JSON or YAML format. The CLI flag can be parsed from the configuration file with periods indicating the hierarchies of the variables. For example, "--some.flag x" becomes `{"some":{"flag": "x"}}`.

The configuration file can be specified using `--config` flag; if unspecified, Grey Matter CLI will search a user's home directory for a file with a name prefixed with `.greymatter` (e.g. `~/.greymatter.yaml`, `~/.greymatter.yml`, etc). The schema of the same configuration shown in the environment variable section above will look like:

```javascript
{
  "api": {
    "host": "services.greymatter.io:443",
    "prefix": "/services/control-api/latest",
    "ssl": true,
    "insecure": true,
    "sslcert": "/path/to/my.crt",
    "sslkey": "/path/to/my.key"
  }
}
```

or

```yaml
api:
  host: services.greymatter.io:443
  prefix: "/services/control-api/latest"
  ssl: true
  insecure: true
  sslcert: "/path/to/my.crt"
  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

{% 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.

## 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 %}