> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ubiquex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# XCL Language Reference

> The complete reference for XCL — block types, expressions, types, and operators.

XCL (eXtensible Configuration Language) is the source language of ubx. It's a declarative, block-based language inspired by HCL. Files use the `.xcl` extension.

## File structure

A `.xcl` file contains a sequence of top-level blocks. Multiple `.xcl` files in the same directory are merged into one compilation unit — the directory is the stack.

```xcl theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
// workspace.xcl — workspace-level config
workspace {
  engine  = "pulumi"
  runtime = "python"
}

// stack.xcl — resource declarations
stack mystack {
  vpc = aws.ec2.Vpc {
    cidr_block = input.vpc_cidr
  }
}

// inputs.xcl — input declarations
input mystack {
  vpc_cidr: string = "10.0.0.0/16"
}

// outputs.xcl — output declarations
output mystack {
  vpc_id = vpc.id
}
```

## Top-level blocks

These blocks appear at the top level of a `.xcl` file:

| Block                                     | Label                         | Purpose                                 |
| ----------------------------------------- | ----------------------------- | --------------------------------------- |
| [`stack`](/v1/xcl/language/stack)         | Identifier                    | Declare cloud resources                 |
| [`input`](/v1/xcl/language/input)         | Identifier                    | Declare typed input fields              |
| [`output`](/v1/xcl/language/output)       | Identifier                    | Declare stack outputs                   |
| [`locals`](/v1/xcl/language/locals)       | Identifier                    | Compute local values                    |
| [`provider`](/v1/xcl/language/provider)   | Identifier (+ optional alias) | Configure a cloud provider              |
| [`workspace`](/v1/xcl/language/workspace) | None                          | Workspace-level config                  |
| [`context`](/v1/xcl/language/context)     | Identifier                    | Per-environment deployment config       |
| [`import`](/v1/xcl/language/import)       | Quoted path                   | Import existing resources               |
| [`remote`](/v1/xcl/language/remote)       | Identifier                    | Reference remote stack outputs          |
| `extend`                                  | Labels                        | Per-environment attribute overrides     |
| `move`                                    | None                          | Rename a resource without recreating it |

`interface`, `policy`, `test`, and `check` are also top-level blocks.

**Block labels are bare identifiers; quotes are optional.** `stack networking` and `stack "networking"` are equivalent (the quotes are stripped). The one exception is `import "path"`, where the quoted string is a resource path, not a label.

<Note>
  `module`, `meta`, and data declarations are **not** top-level — they appear inside a `stack` body. `backend` is not a top-level keyword either; it is a nested block inside `context`, `workspace`, `meta`, or `remote`. See [module](/v1/xcl/language/module), [meta](/v1/xcl/language/meta), [data](/v1/xcl/language/data), and [backend](/v1/xcl/language/backend).
</Note>

## Stack body constructs

Inside a `stack name { }` body you can write:

* **Resource declarations** — `name = Type { … }` (see [resources](/v1/xcl/language/resources))
* **Module calls** — `module name { source = "…" }` (see [module](/v1/xcl/language/module))
* **Deploy targets** — `name = deploy helm { … }`
* **GitOps sync** — `name = sync argocd { … }`
* **Data lookups** — `name = data <type> { … }` (see [data](/v1/xcl/language/data))
* **`meta { }`** — one per stack (see [meta](/v1/xcl/language/meta))

## Keywords

```
stack     input     output    locals    module    provider
import    workspace context   meta      extend    remote
interface policy    test      check     move      data
deploy    sync      for       when      match     default
try       optional  deprecated as       from      true
false     null
```

## Comments

```xcl theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
// Single-line comment

/*
  Multi-line comment
*/

/// Doc comment — attaches to the following declaration
```

## Quick links

* [Expressions](/v1/xcl/language/expressions) — operators, ternary, match, for
* [Types](/v1/xcl/language/types) — string, int, number, bool, list, map, object, optional
* [Secret function](/v1/xcl/language/secret) — `secret("backend", "path")`
* [Built-in functions](/v1/xcl/language/builtin-functions) — `len`, `join`, `split`, etc.