This guide demonstrates how to use tag variables to inject system information into CUE evaluations. A separate guide details how to inject arbitrary information.

One of CUE’s core concepts is that evaluations should be repeatable: given the same input, the same output should be produced. However, sometimes it can be necessary to introduce context or other information into an evaluation that might cause the output to vary. As described in the cue help injection reference, CUE allows information to be introduced, or injected, by using tag attributes and tag variables. This guide demonstrates tag variables.

Injecting system information

Use system information in CUE by including one or more tag variables:

package example

directory:       string @tag(a,var=cwd)
operatingSystem: string @tag(b,var=os)
cpuArchitecture: string @tag(c,var=arch)
currentUsername: string @tag(d,var=username)
currentHostname: string @tag(e,var=hostname)
randomnessA:     int    @tag(f,var=rand,type=int)
randomnessB:     int    @tag(g,var=rand,type=int)
currentTimeA:    string @tag(h,var=now)
currentTimeB:    string @tag(i,var=now)

Make system information available to an evaluation by including the -T flag when invoking a supported cue command:

$ cue export -T --out cue | sort
cpuArchitecture: "arm64"
currentHostname: "7c8be7f9b8ee"
currentTimeA:    "2024-11-21T12:24:01.928819957Z"
currentTimeB:    "2024-11-21T12:24:01.928819957Z"
currentUsername: "root"
directory:       "/home/runner"
operatingSystem: "linux"
randomnessA:     48143939811130088532707076255718137665
randomnessB:     48143939811130088532707076255718137665

In the CUE source, notice that the rand and now tag variables were repeated, and contributed to the values of more than one field. Any tag variable may be repeated, and each repeated use injects the same value inside a single CUE evaluation.

Some variables, such as username and hostname, can be expected to remain stable across CUE evaluations by the same user on the same host. In contrast, the now and rand variables are completely unstable, as demonstrated here by their values being different to the values shown above:

$ cue eval -T | grep -e ^currentTime -e ^random
randomnessA:     256474124597080097645628343043781257633
randomnessB:     256474124597080097645628343043781257633
currentTimeA:    "2024-11-21T12:24:03.630382379Z"
currentTimeB:    "2024-11-21T12:24:03.630382379Z"

Overridding system information

Tag variables are specified in combination with a tag key. For example, as shown above, the randomnessA field is declared to have a relationship with both the rand tag variable and the f tag key:

$ grep ^random tag-variables.cue
randomnessA:     int    @tag(f,var=rand,type=int)
randomnessB:     int    @tag(g,var=rand,type=int)

If a tag key is specified for a cue command then it overrides the system information for fields associated with the tag:

$ cue eval -Tt f=123123123000 | grep ^random
randomnessA:     123123123000
randomnessB:     154463835233876152095912350456117094604

Related content

• How-to Guide: Injecting a value into an evaluation using a tag attribute
• Reference: cue help injection – the cue command’s help text for value and file injection
• How-to Guide: Conditionally including CUE files using build attributes – shorthand tag attributes can also be used as build attributes, which affect which CUE files are included in an evaluation