Skip to content

cli.md

Latest commit

 

History

History
149 lines (108 loc) · 4.61 KB

cli.md

File metadata and controls

149 lines (108 loc) · 4.61 KB
Raw

CLI reference

config-mate loads one root configuration, recursively resolves its $ref values, and serializes the collected document.

Synopsis

config-mate [OPTIONS] CONFIG

config-mate --help
config-mate config.yaml
config-mate config.yaml --output build/config.yaml
config-mate config.yaml --ext json --output build/config.json

CONFIG is required. It can be a local path or a supported URI.

Options

Option Value Default Description
--ext json, yaml, or xml yaml Serialization format of the collected output. The match is case-insensitive.
--output path standard output Write to a file. Missing parent directories are created and an existing file is overwritten.
--oci-hostname text OCI_HOSTNAME Hostname used by the OCI transport adapter.
--oci-username text OCI_USERNAME Username used by the OCI transport adapter.
--oci-password text OCI_PASSWORD Password used by the OCI transport adapter.
--oauth2-bearer text OAUTH2_BEARER Bearer token sent for HTTP and HTTPS requests.
--help — — Show command help and exit.

The output format is controlled by --ext, not by the extension in --output. For example, this command writes JSON despite the .txt suffix:

config-mate config.yaml --ext json --output build/config.txt

Standard output and logs

Without --output, the collected document is written to standard output. Operational logs are emitted separately, so the data can be redirected or piped:

config-mate config.yaml --ext json > build/config.json

Prefer --output when the command itself should create missing parent directories:

config-mate config.yaml --output build/nested/config.yaml

Supported input locations

The root CONFIG and external $ref values can use the transports mounted by the CLI:

Location Example Notes
Local path config/root.yaml Converted internally to an absolute file:// URI.
File URI file:///workspace/config/root.yaml Must use a valid file URI.
HTTP(S) https://example.org/config/root.yaml Optional bearer authentication is applied to both HTTP and HTTPS.
S3 s3://configuration/root.yaml Uses the S3 session adapter and its credential discovery behavior.
OCI oci://registry.example.org/team/root.yaml Uses the OCI options or their environment-variable equivalents.

Input may be YAML, JSON, or XML. For remote inputs, the response Content-Type selects the parser; when that header is absent, Config Mate assumes YAML. Gzip-compressed response bodies are detected and decompressed.

See the $ref reference for fragments and relative resolution.

Remote inputs and authentication

HTTP bearer token

Pass a token as an option:

config-mate https://config.example.org/root.yaml \
  --oauth2-bearer "$CONFIG_TOKEN"

Or expose it through the supported environment variable:

export OAUTH2_BEARER="$CONFIG_TOKEN"
config-mate https://config.example.org/root.yaml

The same HTTP adapter is used when following HTTP or HTTPS references inside the root document.

OCI credentials

Pass credentials directly:

config-mate oci://registry.example.org/team/root.yaml \
  --oci-hostname registry.example.org \
  --oci-username "$OCI_USER" \
  --oci-password "$OCI_PASS"

Or use environment variables:

export OCI_HOSTNAME=registry.example.org
export OCI_USERNAME="$OCI_USER"
export OCI_PASSWORD="$OCI_PASS"
config-mate oci://registry.example.org/team/root.yaml

Environment variables keep credentials out of shell history, but they are still visible to processes with access to the environment. Use the secret facility provided by your CI system.

Output formats

The input and output formats are independent. A YAML root can be collected as JSON or XML:

config-mate config.yaml --ext json --output build/config.json
config-mate config.yaml --ext xml --output build/config.xml

YAML is the default:

config-mate config.json --output build/config.yaml

Exit behavior

The command exits with:

  • 0 after successful resolution and serialization;
  • 1 when loading, parsing, resolving, or writing fails; and
  • Click's non-zero usage exit when arguments or option values are invalid.

Failures are logged with a FAIL marker and the underlying exception. Success is logged with a SUCCESS marker. Do not treat a partially created output file as valid after a failure; only consume the artifact when the command exits successfully.