Config Item @decorators
Decorators in a comment block directly preceeding a config item will be attached to that item. Multiple decorators can be specified on the same line. A comment block is broken by either an empty line or a divider.
# @required @sensitive @type=string(startsWith=sk-)# @docsUrl=https://docs.servicex.com/api-keysSERVICE_X_API_KEY=More details of the minutiae of decorator handling can be found in the @env-spec reference.
Built-in item decorators
Section titled “Built-in item decorators”These are the item decorators that are built into Varlock. Plugins may introduce more.
@required
Section titled “@required”Value type: boolean
Sets whether an item is required - meaning validation will fail if the value resolves to undefined or an empty string.
Default behavior for all items within the same file can be toggled using the @defaultRequired root decorator.
💡 Use the forEnv() function to set required based on the current environment.
# @defaultRequired=false# ---# @required # same as @required=trueREQUIRED_ITEM=
# @required=forEnv(prod)REQUIRED_FOR_PROD_ITEM=
# @required=eq($OTHER, foo)REQUIRED_IF_OTHER_IS_FOO=@optional
Section titled “@optional”Value type: boolean
Opposite of @required. Equivalent to writing @required=false.
# @defaultRequired=true# ---# @optionalOPTIONAL_ITEM=@sensitive
Section titled “@sensitive”Value type: boolean
Sets whether the item should be considered sensitive - meaning it cannot be exposed to the public. The value will be always be redacted in CLI output, and client integrations can take further action to prevent leaks.
Default behavior for all items can be set using the @defaultSensitive root decorator
# @sensitiveSERVICE_X_PRIVATE_KEY=# @sensitive=falseSERVICE_X_CLIENT_ID=Value type: data type (name only or function call)
Sets the data type of the item - which affects validation, coercion, and generated types. Note that some data types take additional arguments. See data types reference for more details.
If not specified, a data type will be inferred when possible, or default to string otherwise.
# @type=url # name onlySOME_URL=
# @type=string(startsWith=abc) # function call with optionsEXAMPLE_WITH_TYPE_OPTIONS=
INFER_NUMBER=123 # data type of `number` will be inferred from the value@example
Section titled “@example”Value type: string
Provides an example value for the item. This lets you avoid setting placeholder values that are not meant to be used.
# @example="sk-abc123"SECRET_KEY=@docs()
Section titled “@docs()”Arg types: [ url: string ] | [ description: string, url: string ]
URL of documentation related to the item. Will be included in generated types. Can be called multiple times.
# @docs(https://xyz.com/docs/api-keys)# @docs("Authentication guide", https://xyz.com/docs/auth-guide)XYZ_API_KEY=
example of docs() info in generated types / IntelliSense
@docsUrl (deprecated)
Section titled “@docsUrl (deprecated)”Value type: string
URL of documentation related to the item.
Use @docs() instead, which supports multiple docs entries with optional descriptions.
@docsUrl=https://example.com -> @docs(https://example.com)