Light Dark Auto

CLI

Configuring the `greymatter` CLI

The greymatter CLI is the official client for communicating with a greymatter.io mesh.

The CLI exposes its functionality through subcommands, and help is available at the command line by passing --help to any subcommand.

Configuration Sources

The CLI evaluates config options in the following order.

  1. Command line flags
  2. Environment variables
  3. Configuration file

The default location of the config is ~/.config/greymatter/config.toml. This can be overridden with the --config command line flag.

GitOps Sync Mode

In addition to interactive use, greymatter supports a continuous sync mode. In continuous sync mode, the CLI will pull service mesh configurations from a repository on an interval, and apply them to the mesh. Changes will only be pushed if the CLI detects remote config has changed, otherwise it will continue to watch.

Configuration File Overview

The config file for greymatter is a single TOML-formatted file with several configuration sections, or stanzas.

Not every section is required, and many options have defaults. Most config options available in the config file are also available via command line flags.

Control Plane API

[api] configuration stanza for the Control API service.

  • url(String) - A protocol scheme (http or https), host and port where the Control API is listening. Can also include an HTTP route prefix portion at the end. Example: http://127.0.0.1:8080 or http://127.0.0.1:8080/v1
  • use_tls(Boolean) - Enables or disables TLS.
  • tls_cert(String) - Path to a pem-encoded TLS certificate.
  • tls_key(String) - Path to a pem-encoded private key.
  • insecure(Boolean) - If true, do not verify the API server's certificate.

Catalog

[catalog] configuration stanza for the Catalog service.

  • url(String) - A protocol scheme (http or https), host and port where the Catalog is listening. Can also include an HTTP route prefix portion at the end. Example: http://127.0.0.1:8080 or http://127.0.0.1:8080/v1
  • use_tls(Boolean) - Enables or disables TLS.
  • tls_cert(String) - Path to a pem-encoded TLS certificate.
  • tls_key(String) - Path to a pem-encoded private key.
  • insecure(Boolean) - If true, do not verify the API server's certificate.

SOCKS5

[socks5] configuration stanza for the CLI to connect through a SOCKS5 proxy.

  • protocol(String) - One of: "tcp", "udp".
  • address(String) - IP address of the SOCKS5 proxy.
  • username(String) - SOCKS5 username
  • password(String) - SOCKS5 password

Sync

[sync] configuration stanza for CLI's sync subcommand. For more information on how to use sync, check out our GitOps guide.

  • root(String) - Path to a directory on disk, the root of a configuration tree.
  • git(Boolean) - If true, sync from a git repository. Setting this is required for other git configurations to take effect.
  • remote(String) - A valid URL for a git remote.
  • git_branch(String) - The branch to check out after cloning (required).
  • git_user(String) - DEPRECATED: A username for HTTP-based authentication to a git remote v4.5+
  • git_password(String) - DEPRECATED: Password for HTTP-based authentication to a git remote. v4.5+
  • git_dir(String) - Path to the directory where a git repository will be cloned and updated
  • ssh_private_key(String) - Path to an ssh key on disk for git authentication.
  • ssh_passphrase(String, default: "") - Passphrase protecting the private key.
  • forever(Boolean) - If true, cli will never exit, but sync on an interval.
  • interval(String, default: "60s") - The interval for a CLI in --forever mode to attempt a sync. Must be parsable as a duration.
  • relative_path(String) - A subpath relative to the root of a git repo.
  • report(Boolean) - Generate a full in-depth sync report in the shell on completion of a sync cycle. Introduced in v4.1.0+
  • cue_package(String, default: "") - Optionally select a single package from within a CUE module. Introduced in v4.2.0+

Redis

[redis] configuration stanza for CLI's sync subcommand. Redis is required for sync to perform its reconciliation against the greymatter.io control-plane.

  • db(Integer) - Redis target database.
  • address(String) - IP address of the Redis instance.
  • username(String) - Redis username
  • password(String) - Redis password

Init

In version 4.5+, we introduced a templating engine along with GSL. All configuration for init is provided through flags which can be found at:

greymatter init --help

Similarly init service can also have config demonstrated through:

greymatter init service --help

Sync

In version 4.5, GSL configuration support was introduced. It has numerous advantages over raw JSON such as comments, templating, and type-checking on top of a composable configuration language for added organization.

Full CLI Configuration Example

This configuration is only an example representation of possible config values, it is not a fully functional file.

log_level = "debug"

[api]
url = "http://127.0.0.1:5555"
use_tls = false
tls_cert = "/path/to/client/cert"
tls_key = "/path/to/client/key"
insecure = true

[catalog]
url = "http://127.0.0.1:8080"
use_tls = false
tls_cert = "/path/to/client/cert"
tls_key = "/path/to/client/key"
insecure = false

[sync]
root = "/path/to/non/git/dir"
git = false
remote = "git@github.com:greymatter-io/gitops-examples.git"
git_branch = "main"
ssh_private_key = "/some/user/.ssh/id_ed25519"
ssh_passphrase = ""
git_dir = "some_dir"
relative_path = "sub_dir"
forever = true
interval = "60s"
cue_package = "mesh"
report = true

[redis]
address = ""
db = 0
password = ""
username = ""

[socks5]
protocol = ""
address = ""
username = ""
password = ""