Config
Categories:
Configuration Sources
Configuration is performed using a JSON/Jsonnet configuration file, environment variables, and command line arguments. Configurations from one source will override previous sources, i.e. environment variables override configuration files, command line arguments override environment variables.
Command Line
Every configuration key can be set using -x <a_config_key1>="a value" -x <a_config_key2>="another value"
, i.e. -x cli_logLevel=debug -x cli_logFormat=kv
. Config values can also be set using JSON, i.e. -x cli='{"logLevel": "debug"}'
Command line values override all other sources.
Environment Variables
Every configuration key can be set using yaml8n_section_key=a value
or YAML8N_section_key=a value
, i.e. yaml8n_cli_logLevel=debug
. A special environment variable, yaml8n_config
can be used to specify a complete JSON/Jsonnet configuration.
Environment Variables override a configuration file.
Configuration File
A configuration file be formatted using JSON or Jsonnet. YAML8n looks for yaml8n.jsonnet
by default, ascending the directory tree to find it. See the Jsonnet reference for more information. Configuration files are rendered at startup, allowing you to use dynamic Jsonnet functions to dynamically alter the config, i.e.:
local getRecord(type, name, fallback=null) = std.native('getRecord')(type, name, fallback);
local level = getRecord('txt', 'level.candid.dev');
{
cli: [
logLevel: level,
],
}
You can view the rendered configuration by running yaml8n config
.
Configuration Values
cli
configPath
String, path to the configuration file. If a filename without a path is specified, Rot will search parent directories for the filename and use the first one found.
Default: ".jsonnet"
configReloadSec
Number of seconds to periodically reload the config and reload the application, if > 0.
Default: 0
configWatch
Boolean, if true then the configPath
will be watched for changes. On a change, the application will be reloaded.
Default: false
logFormat
String, log format to use for logging: human, kv, or raw.
Default: "human"
logLevel
String, log level to use for logging: none, debug, info, or error.
Default: "info"
macros
A map of macros to simplify and template CLI arguments. An example macro looks like this:
{
"cli": {
"macro": {
"mymacro": {
"argumentsRequired": [
"argument1"
],
"flags": {
"d": {
"usage": "D flag usage!"
},
},
"template": "config",
"usage": "Mymacro usage!",
}
}
}
}
This will add the macro, mymacro
to the CLI.
Default: {}
argumentsRequired
A list of arguments that are required for the macro.
Default: []
argumentsOptional
A list of arguments that are optional for the macro.
Default: []
flags
A map of flags for the macro.
Default: {}
default
A list of strings for the default value of the flag.
Default: []
options
A list of strings the flag can be set to.
Default: []
placeholder
String, the placeholder name for the flag if it accepts a value.
Default: ""
usage
String, the usage instructions for the flag.
Default: ""
template
String, the Go template syntax that will be rendered, appended to the CLI, and ran. The Go template can use these custom functions:
{{ getArg i int f string }}
Get an argument at positioni
or return fallbackf
.{{ getEnv e string f string }}
Get an environment variablee
or return fallbackf
.{{ getFlag f string }}
Get the flag values forf
. For flags with a placeholder, this will be an array of string values, otherwise it will be a boolean.{{ join s []string sep string }}
Join arrays
with separatorsep
.
Default: []
usage
String, the usage documentation for a macro.
Default: ""
noColor
Boolean, disables colored log output.
Default: false
noPaging
Boolean, disables paging of log output using less
.
Default: false
checkCode
String, check/validate a specific language code.
Default: ""
defaultCode
String, the default language code to use if none are set in the translation file. Used to globally set the defaultCode
value across multiple translation files or within a monorepo.
Default: ""
failWarn
Boolean, if warnings should cause failures.
Default: false
jsonnet
Configuration toggles for disabling Jsonnet Native Functions. Some of these functions are disabled by default–namely anything that could perform an external call, like running a command, or performing HTTP or DNS requests. These should only be enabled for Jsonnet files you trust, as they could lead to data exfiltration or worse.
disableGetArch
Disable the getArch
function.
Default: false
disableGetCmd
Disable the getCmd
function.
Default: true
disableGetConfig
Disable the getConfig
function.
Default: false
disableGetEnv
Disable the getEnv
function.
Default: false
disableGetFile
Disable the getFile
function.
Default: false
disableGetFileHTTP
Disable the getFileHTTP
function.
Default: true
disableGetOS
Disable the getOS
function.
Default: false
disableGetPath
Disable the getPath
function.
Default: false
disableGetRecord
Disable the getRecord
function.
Default: true
iso639Codes
Map of ISO 639 codes to their pretty name. YAML8n will warn on translations that are missing these codes. Will be used if none are set in the translation file. Used to globally set the iso639Codes
value across multiple translation files or within a monorepo.
Default: {}
licenseKey
String, the YAML8n license key provided to your organization.
Default: ""
translations
String, the path to a translations YAML file.
Default: ""