Light Dark Auto

Greymatter 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.

Sync

In addition to interactive use, greymatter supports a continuous sync mode for performing GitOPs. In continuous sync mode, the CLI will pull mesh configurations from a repository on an interval, and apply them to the mesh only on a detected change. If no change is made, sync will ignore and continue to watch the repository.

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.

Dry Run

In CLI v4.5.6+, a --dry-run flag was introduced into the sync subcommand. Evaluating configuration locally before sync attempts to publish to greymatter should be apart of a workflow while writing greymatter config. Dry running will output all API objects in JSON to stdout of your shell. If evaluation is not successful, validation errors will be printed to stdout.

To perform a dry run, execute the following command at the root of your greymatter project:

greymatter sync --dry-run

To only evaluate a subpath of your project you may also provide the relative-path flag to sync.

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.

Sync

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

  • root(String) - An absolute path to your greymatter project on disk.
  • git(Boolean) - Perform sync with a git repository as the configuration target instead of a project on disk.
  • remote(String) - The target git remote to clone. We recommend using SSH as the protocol.
  • git_remote_ca(String, default: "") - Path to a PEM-encoded CA bundle. Required for HTTPS operations against servers using custom, private CAs.
  • git_tls_skip_verify(Boolean, default: false) - If true, do not verify the server’s certificate. Setting this to true is insecure.
  • git_branch(String) - The target git branch to sync from the specified remote.
  • git_user(String) - A username for HTTP-based authentication to a git remote v4.5+
  • git_password(String) - Password for HTTP-based authentication to a git remote. v4.5+
  • git_dir(String) - A path to an existing repo on disk, or where a repo should be cloned to.
  • ssh_private_key(String) - A path to your local SSH private key on disk.
  • ssh_passphrase(String, default: "") - The passphrase to the supplied SSH private key.
  • forever(Boolean) - Continuously sync on an interval without ever exiting.
  • 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) - An optional sub-path relative to the root of the git repo (or local sync tree).
  • report(Boolean) - Output a full report of syncs actions on completion. Introduced in v4.1.0+
  • package(String, default: "") - Optionally select a single package from within a CUE module.

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 for authentication.
  • password(String) - Redis password for authentication.

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

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 may also have config demonstrated through:

greymatter init service --help

Full CLI Configuration Example

This configuration is only an example representation of possible config values, it is not a fully functional file and should be modified on disk.

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"
report = true

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

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