# Working with HCL

Encode and decode to and from [HashiCorp Configuration Language (HCL)](https://github.com/hashicorp/hcl).

HCL is commonly used in HashiCorp tools like Terraform for configuration files. The yq HCL encoder and decoder support:

* Blocks and attributes
* String interpolation and expressions (preserved without quotes)
* Comments (leading, head, and line comments)
* Nested structures (maps and lists)
* Syntax colorisation when enabled

## Parse HCL

Given a sample.hcl file of:

```hcl
io_mode = "async"
```

then

```bash
yq -oy sample.hcl
```

will output

```yaml
io_mode: "async"
```

## Roundtrip: Sample Doc

Given a sample.hcl file of:

```hcl
service "cat" {
  process "main" {
    command = ["/usr/local/bin/awesome-app", "server"]
  }

  process "management" {
    command = ["/usr/local/bin/awesome-app", "management"]
  }
}

```

then

```bash
yq sample.hcl
```

will output

```hcl
service "cat" {
  process "main" {
    command = ["/usr/local/bin/awesome-app", "server"]
  }
  process "management" {
    command = ["/usr/local/bin/awesome-app", "management"]
  }
}
```

## Roundtrip: With an update

Given a sample.hcl file of:

```hcl
service "cat" {
  process "main" {
    command = ["/usr/local/bin/awesome-app", "server"]
  }

  process "management" {
    command = ["/usr/local/bin/awesome-app", "management"]
  }
}

```

then

```bash
yq '.service.cat.process.main.command += "meow"' sample.hcl
```

will output

```hcl
service "cat" {
  process "main" {
    command = ["/usr/local/bin/awesome-app", "server", "meow"]
  }
  process "management" {
    command = ["/usr/local/bin/awesome-app", "management"]
  }
}
```

## Parse HCL: Sample Doc

Given a sample.hcl file of:

```hcl
service "cat" {
  process "main" {
    command = ["/usr/local/bin/awesome-app", "server"]
  }

  process "management" {
    command = ["/usr/local/bin/awesome-app", "management"]
  }
}

```

then

```bash
yq -oy sample.hcl
```

will output

```yaml
service:
  cat:
    process:
      main:
        command:
          - "/usr/local/bin/awesome-app"
          - "server"
      management:
        command:
          - "/usr/local/bin/awesome-app"
          - "management"
```

## Parse HCL: with comments

Given a sample.hcl file of:

```hcl
# Configuration
port = 8080 # server port
```

then

```bash
yq -oy sample.hcl
```

will output

```yaml
# Configuration
port: 8080 # server port
```

## Roundtrip: with comments

Given a sample.hcl file of:

```hcl
# Configuration
port = 8080
```

then

```bash
yq sample.hcl
```

will output

```hcl
# Configuration
port = 8080
```

## Roundtrip: With templates, functions and arithmetic

Given a sample.hcl file of:

```hcl
# Arithmetic with literals and application-provided variables
sum = 1 + addend

# String interpolation and templates
message = "Hello, ${name}!"

# Application-provided functions
shouty_message = upper(message)
```

then

```bash
yq sample.hcl
```

will output

```hcl
# Arithmetic with literals and application-provided variables
sum = 1 + addend
# String interpolation and templates
message = "Hello, ${name}!"
# Application-provided functions
shouty_message = upper(message)
```

## Roundtrip: Separate blocks with same name.

Given a sample.hcl file of:

```hcl
resource "aws_instance" "web" {
  ami = "ami-12345"
}
resource "aws_instance" "db" {
  ami = "ami-67890"
}
```

then

```bash
yq sample.hcl
```

will output

```hcl
resource "aws_instance" "web" {
  ami = "ami-12345"
}
resource "aws_instance" "db" {
  ami = "ami-67890"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mikefarah.gitbook.io/yq/usage/hcl.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.