Home / The Go API / Loading CUE

Loading CUE

Loading CUE aims to mimic the process the CLI uses to construct a value from entrypoints or arguments. This section and subsections go over the loading process and configuration. The next section deals with managing the the gaps and differences to fully replicate the CLI behavior.

The Loading Process

The CUE loader or cue/load package can be used to load CUE much like the CLI. The process consists of:

specifying the entrypoints or arguments
setting up the configuration
calling load.Instances
turning or building the Instances into a CUE Value

We will first walk through a basic example of this process then look at details and advanced usage.

Loading and Printing CUE Code

This first example shows how to load and build CUE from entrypoints like the cue CLI commands.

simple.go

package main

import (
	"fmt"

	"cuelang.org/go/cue/cuecontext"
	"cuelang.org/go/cue/load"
)

func main() {
	// We need a cue.Context for building after loading
	ctx := cuecontext.New()

	// The entrypoints are the same as the files you'd specify at the command line
	entrypoints := []string{"hello.cue"}

	// Load Cue files into Cue build.Instances slice
	// the second arg is a configuration object, we'll see this later
	bis := load.Instances(entrypoints, nil)

	// Loop over the instances, typically there is only one
	for _, bi := range bis {
		// check for errors on the instance
		// these are typically parsing errors
		if bi.Err != nil {
			fmt.Println("Error during load:", bi.Err)
			continue
		}

		// Use cue.Context.BuildInstance to turn
		// a build.Instance into a cue.Value
		value := ctx.BuildInstance(bi)
		if value.Err() != nil {
			fmt.Println("Error during build:", value.Err())
			continue
		}

		// Validate the value
		err := value.Validate()
		if err != nil {
			fmt.Println("Error during validation:", err)
			continue
		}

		// Print the value
		fmt.Println("value:", value)
	}
}

hello.cue

package hello

hello: "world"

#A: {
	foo: string
}

// to cause a load error, remove the '&'
// to cause a build error, change '#A' to '#B'
// to cause a validation error, change foo to '1'
a: #A & {
	foo: "bar"
}

go run simple.go

value: {
	hello: "world"
	a: {
		foo: "bar"
	}
}

The Go Codec

Configuration

Get CUE support and training from Hofstadter

Published 2025-04-25

Edit this page Create page issue Create project issue