By default, a successful cue export displays the evaluation result on its standard output stream, encoded in JSON:

package one

nested: data: true
aList: [1, 2.2, "3.33"]

$ cue export
{
    "nested": {
        "data": true
    },
    "aList": [
        1,
        2.2,
        "3.33"
    ]
}

Output location: --outfile

You can place the output from a successful cue export invocation in a file instead of the standard output stream default by using the --outfile (-o) flag.

The flag accepts a single value: the name of a file that will receive the result of the command. The file’s name is resolved relative to the current working directory, and must be inside a directory that already exists. If the file already exists and the --force (-f) flag is not present then the cue export command will fail. The pseudo-filename of “-” can also be used to refer to the command’s standard output stream explicitly.

package one

data: {
	value: "A string"
	list: [1, 2]
}

$ cue export --outfile data.yml
$ cat data.yml
data:
  value: A string
  list:
    - 1
    - 2

package one

data: {
	value: "A string"
	list: [1, 2]
}

$ cue export --outfile data.txt -e data.value
$ cat data.txt
A string

Output encoding: --out

As you saw above, the cue export command outputs data encoded as JSON, by default, or encoded in the format inferred from the filename suffix passed to the --outfile (-o) flag. To change this behaviour, use the --out flag to specify the output encoding explicitly. You can specify any data encoding documented in cue help filetypes.

When used without the --outfile (-o) flag, the value of the --out flag specifies the encoding of the output that’s printed to the command’s standard output stream:

package one

nested: data: true
aList: [1, 2.2, "3.33"]

$ cue export --out yaml
nested:
  data: true
aList:
  - 1
  - 2.2
  - "3.33"

An output file’s encoding can also be specified explicitly using the --out flag. Use this if the required data encoding doesn’t match the filename’s suffix:

package one

data: {
	value: "A string"
	list: [1, 2]
}

$ cue export --outfile datafile --out json
$ cat datafile
{
    "data": {
        "value": "A string",
        "list": [
            1,
            2
        ]
    }
}

Output location and encoding: --outfile

Any combination of output location and data encoding can be specified using a qualifier with the --outfile (-o) flag.

Qualifiers are described in cue help filetypes, and can be used to prefix a filename with its required encoding, separated by a colon:

package one

data: {
	value: "A string"
	list: [1, 2]
}

$ cue export --outfile json:datafile
$ cat datafile
{
    "data": {
        "value": "A string",
        "list": [
            1,
            2
        ]
    }
}

package one

nested: data: true
aList: [1, 2.2, "3.33"]

$ cue export --outfile yaml:-
nested:
  data: true
aList:
  - 1
  - 2.2
  - "3.33"

Emitting CUE

The cue export command can emit CUE when the --out flag is passed the value “cue”, or when the output filename ends .cue, or when a cue: qualifier is used with --outfile:

package one

nested: data: true
aList: [1 + 1, 2 * 2, 3 / 3]

$ cue export --out cue
nested: data: true
aList: [2, 4, 1.0]

When emitting data encoded as CUE, as with all cue export invocations, the command succeeds only when the value being emitted is concrete. This means that the CUE emitted by cue export will contain only fields that contain fully-specified values. Additionally, the CUE that cue export emits will contain only regular fields. Any hidden fields, definitions, comprehensions, and other CUE language features will not be present, except insofar as their values affect regular fields:

package one

#A: ["a", "b", "c"]
_B: [1, 2, 3]

C: [
	for a in #A
	for b in _B {
		"\(a)-\(b)"
	},
]

$ cue export --out cue
C: ["a-1", "a-2", "a-3", "b-1", "b-2", "b-3", "c-1", "c-2", "c-3"]

When emitting CUE, cue export defaults to producing CUE that does not belong to any package, regardless of the package(s) being evaluated. This behaviour can be changed using the --package (-p) flag:

package one

nested: data: true
aList: [1 + 1, 2 * 2, 3 / 3]

$ cue export --out cue --package foo
package foo

nested: data: true
aList: [2, 4, 1.0]

Escaping HTML

When you include the --escape flag in a cue export invocation, string values containing the characters &, <, or > are emitted with these characters replaced by their escaped unicode code point equivalents:

package one

someHTML: """
	<a href="https://cue.example?foo=bar&baz=quux">...</a>
	"""

$ cue export --escape
{
    "someHTML": "\u003ca href=\"https://cue.example?foo=bar\u0026baz=quux\"\u003e...\u003c/a\u003e"
}

This feature can also be useful when emitting structured data that’s intended to be placed inside an HTML document.

Conclusion

This guide showed you how to use cue export, and the ways in which you can customize its inputs, operation, and output. The command is often used to produce configurations for commands that require JSON, YAML, TOML, or other encodings – you can read more about this common task in How CUE enables configuration.

Related content

• Reference: The cue export command
• Reference: cue help filetypes
• Reference: cue help eval
• Reference: cue help def
• Concept Guide: How CUE enables configuration.