Configuration Syntax
Warning
This content is part of the legacy version of Waypoint that is no longer actively maintained. For additional information on the new vision of Waypoint, check out this blog post and the HCP Waypoint documentation.
This page describes the syntax of the waypoint.hcl
configuration language.
The waypoint.hcl file uses either HCL or JSON, allowing both human and machine
friendly formats. The recommended and typical format is HCL.
HCL is also used by other HashiCorp products such as Terraform. It is not necessary to know all of the details of HCL syntax in order to use Waypoint, and so this page summarizes the most important details. If you are interested, you can find a full definition of HCL syntax in the HCL native syntax specification.
Parameters and Stanzas
The waypoint.hcl
configuration syntax is built around two key syntax constructs:
parameters and stanzas.
Parameters
A parameter assigns a value to a particular name:
The identifier before the equals sign is the parameter name, and the expression after the equals sign is the parameter's value.
The context where the parameter appears determines what names and value types are valid. Parameter values can also be built up using expressions which allow the value to either be specified literally or generated from other values programmatically.
Stanzas
A stanza is a container for other configuration content:
In this example, app
, build
, and use
are all stanzas.
A stanza has a type (such as app
in this example). Each stanza type defines
zero or more labels that must follow the type keyword. The app
type
expects one label, which is "web" in the example above.
A particular stanza type may have any number of required labels, or it may
require none as with the nested build
stanza type.
After the stanza type keyword and any labels, the stanza body is delimited
by the {
and }
characters. Within the stanza body, further parameters
and stanzas may be nested, creating a hierarchy of stanzas and their associated
parameters.
All of the stanza types that Waypoint supports are listed in the documentation sidebar to the left. The documentation uses placement tables to document the context in which stanzas are valid.
Comments
Waypoint configuration supports three different syntaxes for comments:
#
begins a single-line comment, ending at the end of the line.//
also begins a single-line comment, as an alternative to#
./*
and*/
are start and end delimiters for a comment that might span over multiple lines.
The #
single-line comment style is the default comment style and should be
used in most cases. Automatic configuration formatting tools may automatically
transform //
comments into #
comments, since the double-slash style is
not idiomatic.
Identifiers
Parameter names, stanza type names, variables, etc. are all identifiers.
Identifiers can contain letters, digits, underscores (_
), and hyphens (-
).
The first character of an identifier must not be a digit, to avoid ambiguity
with literal numbers.
For complete identifier rules, Waypoint implements
the Unicode identifier syntax, extended to
include the ASCII hyphen character -
.
Character Encoding and Line Endings
Waypoint configuration files must always be UTF-8 encoded. While the delimiters of the language are all ASCII characters, Waypoint accepts non-ASCII characters in identifiers, comments, and string values.
Waypoint accepts configuration files with either Unix-style line endings (LF only) or Windows-style line endings (CR then LF), but the idiomatic style is to use the Unix convention, and so automatic configuration formatting tools may automatically transform CRLF endings to LF.