»Configuration Syntax

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:

image_id = "abc123"

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:

app "web" {
  build {
    use "docker {
      dockerfile = "${path.app}/Dockerfile"
    }
  }

  # ...
}

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.