v0.17.0-alpha.3

Changes which may break some users are marked below with: ⚠️

Evaluator

Several long-standing cycle-detection bugs have been fixed, such as self-referential uses of matchN and matchIf, self-feeding disjunctions, and comprehensions that read a let binding which refers back to the comprehension's own fields.

Fixed a bug where the same package imported via different qualified import paths (e.g. foo.com/bar@v0 or foo.com/bar:baz) did not share the same hidden field namespace.

Fix a data race which could occur when concurrently loading the same imported packages.

cmd/cue

Module replace directives

cue now supports replace directives, letting you substitute a module dependency with a local directory or a different remote module during development - for example while testing a fix to a dependency before it is published, or to replace a dependency with a fork including improvements.

This configuration lives in cue.mod/local-module.cue, which is excluded when publishing to registries. cue mod edit and cue mod tidy gain support for maintaining this file.

We have also published a how-to guide on replacing a dependency with a local module.

Read the full design and provide feedback in the proposal, or read the cue.mod/local-module.cue reference docs.

Other changes

Resolving an unversioned import from a dependency module now respects that module's own default major version, instead of always using the main module's default.

Fix a bug where the flag cue export --path was ignored when the inputs were pure CUE.

cue import --with-context now ensures that data represents the original raw input data, and not its interpretation like JSON Schema.
Command input parsing is improved so that CUE packages can come after data files, such as cue vet -c data.yaml ./schema.

A $CUE_CACHE_DIR directory is no longer required when loading CUE without external dependencies.

Standard library

Add time.ToUnix and time.ToUnixNano, which convert an RFC3339Nano time value into seconds or nanoseconds since the Unix epoch, complementing the existing Unix builtin.

Go API

⚠️ The modconfig.Registry interface is changed to report default major versions, which is required for resolving unversioned imports against each dependency module's own defaults. Clients that implement or wrap the interface will need to update. The new interface is future-proofed for upcoming modules changes.

Full list of changes since v0.17.0-alpha.2

• cmd/cue: reject non-string label values for --path by @mvdan in 5a0f4f7
• cmd/cue: add test for --path with a non-string label value by @mvdan in 772d1d3
• update dependencies ahead of v0.17.0-alpha.3 by @mvdan in b7d1625
• cmd/cue: drop github.com/google/shlex test dependency by @mvdan in 69bf7d7
• cue/load: accept package arguments after file arguments by @mvdan in dd80111
• cmd/cue: add test for package arguments listed after files by @mvdan in ed3622b
• internal/cuetxtar: port old stats framework by @mpvl in 489b249
• encoding/ini: pass token.Pos through the decoder directly by @mvdan in 91a3f18
• encoding/ini: minor decoder cleanups by @mvdan in 5b8ba6e
• encoding/ini: reject section and property name collisions by @mvdan in eb8ac73
• cue/testdata: add missing error output for issue2627 by @mpvl in 092c281
• Revert "cue/errors: augment paths of wrapped errors" by @mvdan in a361a5b
• cmd/cue: add replace directive support to mod edit by @rogpeppe in 9984dae
• internal/mod/modload,mod/modzip,cmd/cue: tidy and publish two-file modules by @rogpeppe in 5adf7f5
• mod/modfile,cue/load: read replace directives from local-module.cue by @rogpeppe in 12ecd27
• all: add core plumbing for module replace directives by @rogpeppe in 74d78c1
• cue/build,cue/load: fix hidden-field namespace for versioned imports by @rogpeppe in b159ed1
• cue/testdata: add regression test for issue #2937 by @mvdan in 39d5c4e
• cue/errors: augment paths of wrapped errors by @mvdan in 71c13d2
• pkg/encoding/json: add test for Validate hiding the failing field by @mvdan in 8507be6
• pkg/time: add ToUnix and ToUnixNano builtins by @mvdan in d5a3fb7
• cmd/cue: honor -l/--path when exporting CUE values by @mvdan in 0abb86e
• cmd/cue: add test for export -l with CUE output by @mvdan in 14d7d4d
• all: make more use of string cut/trim/contains APIs by @mvdan in 40ad26f
• internal/mod/modpkgload,cue/load: resolve major version defaults per module by @rogpeppe in b24b39c
• cue: format builtin call's function operand as a bare reference by @mvdan in 7392c8e
• cue: add test for builtin call function operand formatting by @mvdan in 72ff12b
• cue/parser: support try clauses in list literals by @mvdan in b0a4125
• cmd/cue: point to 'cue help flags' from the --with-context flag by @mvdan in 8b9f8be
• cmd/cue: evaluate --with-context labels against the source data by @mvdan in 9bb021f
• mod/modconfig: lazily initialize registry clients by @mvdan in 44f24f1
• cmd/cue: test various command scenarios without cache/config dirs by @mvdan in 445c76d
• cmd/cue: add test for label references with jsonschema import by @mvdan in f33b9de
• internal: only wrap over-long generated comment lines by @mvdan in b682521
• encoding/jsonschema: add test for doc comment reflow by @mvdan in fa683ed
• internal/core/adt: handle cycle placeholder for composite builtins by @mpvl in 32244d1
• internal/core/adt: guard nodeContext free on refCount by @mpvl in 03748aa
• internal/cuetxtar: fix inline runner writeStruct cycle and BasicType embed by @mpvl in afa5272
• cue/testdata: add test case demonstrating #2627 reopen by @mpvl in 684e354
• internal/core/adt: resolve imports to a per-evaluation instance by @mvdan in 86eb4f1
• cmd/cue: add test cases for issues 4370 and 4371 by @rogpeppe in 230bbbb
• internal/mod: minor module-related code improvements by @rogpeppe in 964c012
• internal/core/adt: test optional field referencing pushed-down comprehension by @mvdan in 32e6da5
• encoding/jsonschema: compile CRD schema only once by @mvdan in 139794b
• internal/core/adt: attribute failed try references to the owning body by @mvdan in 8c8c47c
• cue/testdata: add regression tests for nested try clauses by @mvdan in f7a59da
• internal/core/adt: fire comprehensions on let-bound self references by @mvdan in f6d7894
• internal/core/adt: add test for comprehensions on let-bound self references by @mvdan in c60ba81
• internal/core/adt: bound self-feeding disjunction recursion in cycle detection by @mvdan in 43d216f
• cue/testdata: add a test for the cycle-detection blowup of issue #4377 by @mvdan in e7d5121
• cue: add regression test for FillPath exporting fields as optional by @mvdan in 00df6eb
• internal/core/compile: detect structural cycles in self-referential matchIf by @mvdan in ec1313c
• internal/core/compile: detect structural cycles in self-referential matchN by @mvdan in d1a6540
• cue: accept a leading index in ParsePath by @mvdan in 0b61fdf
• cue: add TestPaths cases for a leading index in a path by @mvdan in a035333
• cue: give each TestPaths case its own CUE input by @mvdan in 5cf0e58
• pkg/list: add regression test for list.Contains with defaults by @mvdan in 7c6d8ae

v0.17.0-alpha.2

Changes which may break some users are marked below with: ⚠️

Language

The parser now allows a newline or a comma before the closing bracket of an index expression, matching how lists and func arguments allow omitting trailing commas:

foo[
    "bar"
]

Evaluator

The comprehension algorithm now waits to run a comprehension's body until the fields it reads have a concrete value, rather than trying to produce its fields up front. This resolves a number of long-standing bugs, most notably the last known regressions from evalv2, where a comprehension that should have resolved instead failed as an incomplete value or a cycle.

This design also greatly simplifies upcoming evaluator work, such as introducing new builtins to replace comparing values to bottom, as well as the design of evalv4.

The evaluator no longer deduplicates errors just by position, which was causing some useful errors from disjunctions or standard library calls to be dropped incorrectly.

A number of bugs, panics, and hangs have been resolved as well.

cmd/cue

cue vet -d/--schema now supports hidden fields, and correctly reports an error when the command inputs are CUE only.

cue fix and cue trim no longer change file modification times when no changes are necessary.

Encodings

⚠️ The experimental JSON Schema encoder now emits most definitions without the leading # character, shortening names and ensuring compatibility with the wider JSON Schema ecosystem. This required deprecating encoding/jsonschema.GenerateConfig.NameFunc in favor of NamesFunc.

Several closedness bugs in the JSON Schema encoder have been fixed, ensuring that the generated JSON Schema behaves the same way as the original CUE definition.

The ProtoBuf decoder now resolves relative references following the usual scoping rules, instead of always resolving them against the top-level scope.

Go API

Add Path.Compare and Selector.Compare, providing allocation-free total ordering suitable for slices.SortFunc.

Full list of changes since v0.17.0-alpha.1

• .claude: add a skill to draft release notes from a commit log by @mvdan in 7935fe8
• internal/ci: bump Go and goreleaser for the upcoming alpha by @mvdan in c2a8155
• encoding/jsonschema: mark generation as experimental by @rogpeppe in 223cfa7
• encoding/protobuf: translate google.protobuf.Struct to an open struct by @mvdan in ef3e0ee
• internal/core/adt: report true element count for list length mismatch by @mvdan in d474938
• cue/testdata: add test for list-length error with comprehensions by @mvdan in 40961bb
• cue: fix Value.ReferencePath after Eval when sharing is disabled by @mvdan in 9a6d76d
• cue: clarify Value.ReferencePath path semantics by @mvdan in 0adb8dd
• pkg/list: report a missing less field as a fatal error by @mvdan in 6aa4a11
• cmd/cue: fix vet -d resolving a hidden constraint by @mvdan in 5651def
• cmd/cue: add test for vet -d with a hidden constraint by @mvdan in 1a0c02c
• pkg/encoding: report every Validate conflict by @mvdan in 81f9d1b
• pkg/encoding: add tests for Validate reporting a single conflict by @mvdan in 5310062
• mod/modconfig: delete the dummy $DOCKER_CONFIG dir when the tests are done by @mvdan in ffb2fbd
• cue/errors: deduplicate without rendering errors unnecessarily by @mvdan in e9f02ca
• cue/errors: report all distinct errors at the same position by @mvdan in 774942d
• cue/errors: add a test recording how often removeMultiples renders errors by @mvdan in 2ba0d46
• cue/errors: add tests for distinct errors dropped at the same position by @mvdan in a753484
• modconfig: update ociregistry to pick up ociauth fix by @mvdan in e5e958e
• internal/core/debug: only print integer-labeled arcs of a list value by @mvdan in 8fdf9d5
• pkg/list: add a regression test for list error printing hidden arcs by @mvdan in f9b4c66
• internal/filetypes: clarify error for combined file type and file name by @mvdan in b15022d
• cmd/cue: add a regression test for issue 3187 by @mvdan in 8273d6f
• cue: avoid panic in Value.Path for dereferenced let bindings by @mvdan in 58f2356
• internal/core/adt: recompute cached let results that resolved to a cycle by @mvdan in 4a67df9
• cue/testdata/cycle: add regression test for issue 4357 by @mvdan in ffc0541
• cue/testdata: add #4149 regression test for or structural cycle by @mvdan in 803c837
• internal/cuetxtar: keep nested inline positions relative by @mpvl in dede65a
• internal/core/adt: detect structural cycle through inline conjunction by @mvdan in f518389
• internal/core/compile: update compile file comments by @mpvl in 5a6110a
• internal/core/adt: loosen structure-sharing skip in cycle detection by @mpvl in aae3830
• internal/core/adt: bound self-recursion in cycle detection skip by @mpvl in 297d254
• internal/core/adt: do not treat structure sharing as a cycle by @mpvl in c37cf24
• internal/core/adt: scope task context error before deferred tasks by @mpvl in 697512f
• cue/testdata: add #4367 regression tests by @mpvl in 2735d5a
• internal/core/adt: skip typo check on cross-context Finalize by @mpvl in a9f3f2a
• all: adopt the cueckoo @-import guidance mechanism by @myitcv in 5f10676
• all: fix reversed argument order in cmp.Diff calls by @mvdan in 82d70cb
• cue/testdata/cycle: add regression test for issue 3364 by @mvdan in 40caafe
• encoding/protobuf: respect lexical scoping rules by @SteveRuble in d34b9f5
• internal/mod/modregistry: bump ociregistry to merge auth sources by @mvdan in 033671e
• cmd/cue: add test for mixing Docker and Podman auth files by @mvdan in 268fe24
• internal/core/adt: skip in-flight nodes when reclaiming buffers by @mpvl in 489f4a9
• cmd/cue: preserve mtimes in cue fix and cue trim no-op rewrites by @mvdan in 28b3474
• cmd/cue: document mtime drift in fix and trim by @mvdan in e56df9e
• cue/parser: allow a newline before the closing bracket of an index expression by @mvdan in fa44ce4
• cue/testdata: add regression test for self-referential builtin cycles by @mvdan in abe46a1
• internal/core/compile: include label-aliased fields in cross-file scope by @mvdan in 4157262
• cue/testdata: add test for issue #4312 by @mvdan in 9888e6f
• internal/core/export: fix label references in pattern constraints by @mvdan in 0c639f4
• internal/core/compile: strip @test attributes from mirrored inputs by @mpvl in b343757
• internal/core/adt: flush label-only cyclic CallExpr deferments by @mpvl in dd5b4c0
• update dependencies ahead of the next alpha release by @mvdan in 2fddd86
• cmd/cue: fix json error tests on Go tip by @mvdan in bd45f3e
• cue/testdata: add comprehension pushdown regression for inline conjunction iterator by @mpvl in 29b71ea
• encoding/ini: make dotted section-name nesting configurable by @ReginaZhangMS in cd0f418
• internal/core/adt: remove unused nodeContextState.hasOpenValidator by @mvdan in ae29eac
• internal/core/adt: remove unused Bottom.Permanent field by @mvdan in 8f8a581
• internal/core/adt: remove unused Bottom.ForCycle field by @mvdan in b24e6fd
• internal/core/adt: remove unused StructLit.isComprehension field by @mvdan in 0e0dbc1
• internal/core/adt: remove unused StructLit.IsOpen field by @mvdan in 023bcd0
• internal/ci: set GORACE in the base config by @mvdan in 0e2745d
• internal/core/adt: fix data race in concurrent FillPath by @mvdan in 06056b9
• pkg/tool/exec: default env to an empty struct by @mvdan in 74211d7
• cmd/cue/cmd: add test for exec.Run JSON marshaling by @mvdan in f44f49a
• all: make use of strings.CutPrefix by @mvdan in 34f13a2
• cue/test...

v0.17.0-alpha.1

Changes which may break some users are marked below with: ⚠️

Language

The active try experiment renames the new fallback keyword, used with for comprehensions, to otherwise. fallback continues to be accepted for now, but is rewritten to the new form.

The active aliasv2 experiment now allows ~(X) as an alternative to ~X for the single postfix alias form. ~X is also rewritten as ~(X) for the sake of consistency and clarity.

Language versions v0.17.0 and later allow omitting commas in multi-line lists. Just like a newline after a struct field implies a comma, a newline after a list element now implies a comma as well.

The language spec is tweaked to make $ a valid identifier, which was already allowed by the parser and evaluator.

⚠️ Support for the infix div, mod, quo, and rem operators has been removed. Since late 2020, these infix forms have been undocumented and rewritten by cue fix to the new function calls.

The new shortcircuit experiment

This release introduces the shortcircuit experiment, which changes the && and || operators to not evaluate the right operand if the left operand alone determines the result.

This matches the behavior already documented in the CUE spec and is consistent with most mainstream languages, but for the sake of a smooth transition for end users, we are rolling out this change via an experiment.

You can try this experiment via the @experiment(shortcircuit) file attribute. To mimic the old behavior with the experiment, you can use a hidden field:

_y: Y
if X && _y {}

Evaluator

Fix a number of issues where cue def could produce invalid CUE output, such as due to name conflicts.

Fix an evaluator regression where embedded disjunctions across packages may not correctly apply closedness.

Fix an evaluator bug where cue.Context.BuildExpr of close({}) did not actually result in a closed struct.

Fix a bug where some calls to standard library functions or validators did not include the "error in call to pkg.Func" error context, or included it twice.

A few changes to the evaluator should reduce allocated objects by up to 16%, reducing GC overhead and memory usage.

cmd/cue

The new global -C or --chdir flag runs cue from the given working directory.

cue import --path now skips over null values in an input stream, such as empty documents in a YAML file.

The new cue exp gengotypes --outfile flag controls the output file path when generating a single package.

LSP server

Add an initial version of organize-imports, which sorts the existing imports and removes unneeded imports. It is not yet capable of suggesting missing imports.

Wait for a short period of inactivity before sending diagnostics to the editor. This "debounce" means that a user typing incomplete CUE syntax will not be distracted with syntax errors as much.

The aliasv2 experiment is now fully supported.

The rename function is fixed to distinguish between field names and aliases.

Improve field name analysis in general so that fields with multiple aliases (e.g. v=[k=string]: _) are properly supported.

Improve attribute handling for file-level embedded attributes, and to attach attributes within expressions to the correct struct.

Treat conjunctions (&) and disjunctions (|) the same way for goto-definition. With the cursor on a path, it returns all results that the path MAY resolve to. With the cursor on a field declaration name, it returns all results that the path constructed from the field's name, and its field's name (and so on) MAY resolve to.

Special-case close function calls so that paths can resolve through fields within the argument to close.

Encodings

The JSON Schema decoder is improved to better handle the prefixItems keyword.

The JSON Schema encoder is improved to support list.UniqueItems and standalone validators, to use maxItems and minItems instead of maxLength and minLength for lists with prefix elements, and to generate description keywords for doc comments.

Standard library

The net IP APIs now consistently return an error on invalid input types.

strconv.FormatFloat now accepts a string format parameter, like FormatFloat(3.14, "e", 4, 64).

list.MatchN now shows what expected value it's matching against when it fails.

Go API

Using cue.Values concurrently is now fully supported, which required deprecating cue.Value.Context. If you encounter any races or bugs, please report them.

cue/load now supports loading from an io/fs.FS, as outlined in proposal #4285. Loading file embeds through Config.Overlay and Config.FS is supported now as well.

cue/ast/astutil deprecates Sanitize in favor of the new SanitizeFiles API, given that Sanitize on a single file cannot know if another file in the same package shadows builtin names like self.

Clarify that cue/format indents with a tab width of 4 by default.

A new fuzzer has been introduced in the cue package, checking that the parser doesn't crash and that its results are consistent with the rest of the Go APIs like cue/literal. So far, it has already resulted in seventeen bug fixes.

The cue.Interpreter option API has been deprecated in favor of cue.WithInjection, which is a better name going forward.

⚠️ cue/ast.File.Imports, deprecated in mid 2025 in favor of cue/ast.File.ImportSpecs, is now removed.

⚠️ The long-deprecated and hidden cue.Instance methods Lookup, LookupDef, LookupField, and Fill are now removed.

Full list of changes since v0.16.0

• internal/ci: bump Go and goreleaser versions for v0.17.0-alpha.1 by @mvdan in d11a8f8
• cue/ast/astutil: deprecate Sanitize in favor of SanitizeFiles by @mvdan in 89b80ad
• cmd/cue/cmd: add regression test for hidden fields like _5 by @mvdan in 1ed8051
• cmd/cue/cmd: add regression test for vet list.Contains errors by @mvdan in c2f7338
• update dependencies ahead of v0.17.0-alpha.1 by @mvdan in 03f2868
• cue/testdata/cycle: add test for issue #4253 by @mvdan in f31ac4d
• encoding/ini: introduce an INI decoder by @ReginaZhangMS in e5482ee
• cue/load,internal/mod/modpkgload: respect nested cue.mod boundaries by @mvdan in de61149
• all: use slices and maps iterators for collect-and-sort patterns by @mvdan in 8345fc2
• cmd/cue/cmd: document wrong nested-module behavior for issue 2707 by @mvdan in 8ff6cee
• all: use strings.SplitSeq and strings.Cut to avoid intermediate slices by @mvdan in 1ea5ad5
• all: fix stray and misplaced doc comments by @mvdan in 64eaf2f
• cue/inject/embed: resolve files via cue/load.Config's FS or Overlay by @mvdan in b0ce1f5
• internal/core/export: sanitize Profile.Value output by @mvdan in d846deb
• cue: add regression test for predeclared builtin shadowing in %v by @mvdan in 6040780
• cmd/cue: list user-defined commands in cue cmd --help by @mvdan in fbcd9f7
• internal/core/export: mark predeclared builtin references as such by @mvdan in d3187e5
• internal/core/export: add test for predeclared builtin shadowing by @mvdan in 922493a
• internal/core/adt: fix conjunction semantics for opened embeddings by @mpvl in 619d46e
• tools/fix: extract and extend explicitopen fix by @mpvl in 349c457
• cmd/cue: add -C flag, like go and git by @mvdan in 079f1a3
• internal/core: __reclose: detect and restore non-recursive closing by @mpvl in 3091146
• tools/fix: add inline @test framework by @mpvl in f679d39
• cue/ast/astutil: detect aliasv2 postfix label-name redeclarations by @mvdan in 27b5e67
• cue/ast/astutil: add test coverage for redeclared alias errors by @mvdan in 6d45692
• internal/core/adt: document why toComplete hook must stay by @mpvl in 5ae2c12
• internal/core/adt: remove completeNodeTasks from doDisjunct by @mpvl in a6b5a9f
• internal/core/adt: strengthen field-set and arc-type checks by @mpvl in 5750aa5
• .claude: remove deny clause by @rogpeppe in aa0b641
• encoding/jsonschema: support description keyword by @rogpeppe in 70043a5
• cue: allow and enforce parens for single postfix alias by @mpvl in d05d75f
• internal/core/adt: remove dead code in process and evalStateCI by @mpvl in 1ebe938
• internal/core/adt: fix error propagation bug in inline structs by @mpvl in 881d9cf
• internal/core/adt: remove support for list task dependencies by @mpvl in 75af110
• internal/core/adt: remove taskPos field from scheduler by @mpvl in 003a182
• internal/core/adt: add handleParents and processAncestors by @mpvl in 61fb61b
• cue/ast/astutil,tools/fix: add cross-file shadowing detection for predeclared ide...

v0.16.1

Language

The fallback keyword in the aliasv2 experiment is replaced by otherwise, which is clearer. cue fmt or cue fix can be used to rewrite existing code.

Evaluator

Fix a regression where the compiler could add comments to the input AST value, which could lead to increased memory usage.

Fix a bug where exporting certain schemas could result in "cannot have both alias and field in same scope" errors.

cmd/cue

Fix a panic which could occur when using non-label expressions in the --path flag.

Teach cue login to give helpful errors when used with OCI registries which don't support the OAuth2 device flow.

Go API

Fix a regression where cue.Context.Encode could panic on custom marshaler types with pointer receivers.

Full list of changes since v0.16.0

• internal/cueversion: bump to v0.16.1 by @mvdan in 6d609d7
• internal/ci: build releases with Go 1.26.2 by @mvdan in cedf4c8
• update all golang.org/x/... dependencies by @mvdan in b4efeef
• all: rename fallback keyword to otherwise by @mpvl in f813811
• lsp/cache: improve rename by @cuematthew in 8e47027
• integration/workspace: add test showing bad behaviour by @cuematthew in a5e0ef5
• cmd/cue: suggest docker/podman login when OAuth2 device flow is unsupported by @mvdan in c169605
• cmd/cue: add testscript for cue login when device code endpoint is unsupported by @mvdan in d7c882a
• cmd/cue: clarify how to authenticate with standard OCI registries by @mvdan in 2613edf
• internal/core/compile: avoid mutating AST by @rogpeppe in e4b0516
• internal/core/export: fix alias/field name conflict in pattern constraints by @mvdan in 1e46409
• internal/core/export: add regression test for alias/field name conflict by @mvdan in 1654f66
• pkg: fix godoc mistakes across several packages by @mvdan in eae9aaf
• internal/core/convert: fix panic when encoding pointer-receiver marshalers by @mvdan in 8e39aec
• cmd/cue: return an error for non-label --path expressions instead of panicking by @mvdan in 5a55849
• encoding: add godoc hints for cue/ast result types by @mvdan in 682c663

v0.16.0

Changes which may break some users are marked below with: ⚠️

Language

As a reminder, we have two ongoing language experiments since v0.15; a replacement for struct embedding and a rework of aliases. Please give these a try and report any issues or feedback!

⚠️ The cmdreferencepkg global experiment is now stable, meaning that CUE_EXPERIMENT=cmdreferencepkg is always enabled.

#"""# is now accepted as a string literal quoting a double quote, ".

Multiline string literals now require a trailing newline, matching the language spec.

The new try experiment

This release introduces the try experiment, which adds a try clause in comprehensions as well as the use of ? in field selectors. This addition to the language is intended to provide a more concise syntax for handling optional fields without the risk of unintentionally swallowing errors.

This experiment also introduces the else clause for if and try comprehensions, and the fallback clause for for comprehensions, which trigger when a comprehension produces zero values.

You can try this experiment by following our how-to guides on the try clause and the else clause. For more information, see the proposal on GitHub and the spec change patch.

Evaluator

Performance

Further improve the use of caching in the typochecker algorithm; this provides speed-ups of up to 80% on some large projects.

Very large structs (tested with 20,000 fields) are up to 80% faster now, as we were repeating some work unnecessarily.

A great deal of effort has gone into reducing the allocations and memory usage across a number of projects. For some of these, memory usage is down by as much as 60%.

These improvements were possible thanks to our Unity service, letting us analyze CUE's performance and test for regressions on third party projects. Contact @mvdan on Discord, Slack, or via the Unity page to ensure that your project is included or you are running into slowness.

A number of changes were made to improve support for using cue.Values concurrently; see Issue #2733 for more details and ongoing progress.

Other changes

Fix a regression introduced in v0.13 where the or built-in with literal arguments could stop behaving like a disjunction.

A number of panics and other bugs in the evaluator which were reported since v0.15.0 have been fixed; thank you to all who reported these.

cmd/cue

Add support for $DOCKER_AUTH_CONFIG to directly provide the contents of $DOCKER_CONFIG/config.json to authenticate with module registries, matching Docker's current behavior.

The --outfile flag now works when given non-regular files such as named pipes or sockets.

⚠️ cue mod publish no longer ignores sub-directories containing a go.mod file.

⚠️ Using cue inside the cue.mod directory now fails consistently with a clear error message to not place CUE code there. Previously, some commands worked while others failed with confusing errors.

⚠️ The global --verbose and --trace flags have been moved to the cue get go and cue trim commands respectively, as they were the only ones actually using those flags, and this could be confusing to users.

Fix a bug where loading ./...:pkgname could lead to loading directories without CUE files as instances, which could cause poor performance for CUE packages with multiple parent directories.

cue exp writefs gains an encoding optional field for regular files, to specify an encoding rather than infer it from the filename extension.

LSP server

Initial LSP support for editing embedded JSON and YAML files. This feature provides completions and hover-docs when editing JSON or YAML files which are embedded into CUE via the @embed attribute. A teaser video is available on YouTube.

Code Actions: two code actions are now provided, Add surrounding struct braces and Remove surrounding struct braces, which convert between

a: b: c

and

a: {
	b: c
}

with the cursor on b.

A complete overhaul of how the LSP server suggests code completions. This solves the previous naïve implementation which would only make suggestions after a field name or path had been started. Now completions are available from within whitespace.

Embedded paths with mutual dependencies: embedded paths with multiple components (e.g. a.b.c) can in some cases only be fully resolved after the resolution of other embedded paths. The LSP server can now correctly handle these dependencies.

The LSP server now implements LSP Document Symbols functionality. This is often used by editors to provide light-weight breadcrumb navigation within a file.

Some preliminary diagnostics are now sent from the LSP server back to the editor. Initially this mainly indicates syntax errors in CUE files, but this can be extended in the future.

Many bug fixes, including better behaviour for files and directories with spaces; improvements for value aliases (foo: L=x); LSP rename now provides placeholder text; improved jump-to-definition behaviour for package-level fields; fixed issues around imports; path resolution; formatting of standalone CUE files; and others.

See our Getting Started wiki page for instructions on how to set it up with your editor.

Please report any bugs or missing features you encounter via the Issue tracker or via the #lsp channels on Discord or Slack.

Encodings

Add support for encoding YAML tags like key: !Custom value by using CUE attributes like key: "value" @yaml(,tag="!Custom").

cue get go now detects which Go packages use Kubernetes type semantics via // +k8s:openapi-gen=true and obeys the field annotations // +optional and // +nullable.

cue get go gains a --codec flag to configure the use and priority of Go struct field tags like json or yaml.

Fix a bug where cue get go could skip over fields whose type implements one of the supported marshaling interfaces.

Fix a few bugs where cue get go could result in invalid or failing CUE code.

JSON Schema's Config.OpenOnlyWhenExplicit option is now exposed for the CLI via the filetype tag jsonschema+openOnlyWhenExplicit.

JSON Schema now properly encodes hash references for better compatibility with other tools.

Standard library

The strconv package adds ParseNumber, like ParseInt or ParseFloat but allowing other CUE number strings such as 1Ki.

The net package adds InCIDR to test whether an IP is contained by a CIDR string.

The net package adds ParseCIDR to extract useful information from a CIDR string.

The net package adds CompareIP to compare two IP addresses, which can be useful for computing with IP ranges.

The net/http package adds Serve as an experimental API to listen on a port and serve HTTP requests.

The tool/file package adds Symlink to create symbolic links.

Go API

cue.Value.Decode now supports the new cue.Unmarshaler interface, allowing Go types to implement their own CUE value decoding logic via an UnmarshalCUE(cue.Value) error method.

The new cue.IsIncomplete function reports whether the given value is a CUE incomplete error.

cue/ast gains the NewPredeclared and Ident.IsPredeclared to mark and detect identifiers referencing predeclared names like error or int rather than fields which may shadow those names in the current scope.

⚠️ cue.Value.Decode now uses cue.IsIncomplete to not treat incomplete errors as fatal, allowing the decoding to continue.

Fix a bug where cue.Value.Decode could behave incorrectly when decoding a CUE null or incomplete value.

⚠️ cue/token.Compare now sorts absolute paths before relative ones, to ensure consistent behavior between Unix-like systems and Windows.

⚠️ The long-deprecated cue/ast.Node.Comments and cue/ast.Node.AddComment interface methods are now removed; use cue/ast.Comments and cue/ast.AddComment respectively.

⚠️ The long-deprecated and unused cue/parser.FromVersion and cue/parser.DeprecationError APIs are now removed.

⚠️ The long-deprecated and hidden cue.Instance.Eval method is now removed.

Full list of changes since v0.15.0

• internal/ci: use OIDC with the Central Registry for the e2e tests by @mvdan in de47a5e
• re-enable sta...

v0.16.0-rc.1

Changes which may break some users are marked below with: ⚠️

Language

As a reminder, we have two ongoing language experiments since v0.15; a replacement for struct embedding and a rework of aliases. Please give these a try and report any issues or feedback!

⚠️ else is now part of the try experiment

v0.16.0-alpha.2 introduced the else comprehension clause, available to any module targetting language version v0.16.0 or later without needing to use an experiment.

Thanks to user feedback and design discussions, we have come to realize that the existing design needed tweaking. for comprehensions now use a fallback token rather than else in order to clarify intent, and we have also restricted the use of else in chains of comprehension clauses, which could easily cause confusion.

Given how late in the release cycle we already are, and understanding that we probably will want to make further tweaks to this feature before it's stable, we have decided to put this language feature behind a file experiment after all.

Rather than adding @experiment(else), we have chosen to bundle this with @experiment(try), given that try without else does not make much sense.

For more information on the up-to-date else and fallback clauses, follow our how-to guide, or read the updated spec change patch.

Evaluator

Fix a regression introduced by v0.16.0-alpha.2 where cue cmd could suddenly report undefined or missing fields from data in non-tool CUE files.

cmd/cue

cue exp writefs gains an encoding optional field for regular files, to specify an encoding rather than infer it from the filename extension.

Full list of changes since v0.16.0-alpha.2

• lsp/eval: add support for comprehension else/fallback by @cuematthew in e2d8f7b
• cmd/cue: support explicit encodings in exp writefs by @mvdan in d0eca3f
• cmd/cue: rewrite exp writefs with internal/filetypes and internal/encoding by @mvdan in 766668d
• cmd/cue: add first exp writefs testscript by @mvdan in 00eddbf
• internal/core/adt: missed missing missing by @mpvl in 8732213
• cue/parser: simplify else/fallback clause rules by @mpvl in 0cbc9a1
• cue/parser: restrict else to single clause only by @mpvl in 28f0246
• cue: add fallback keyword for for comprehensions by @mpvl in fe9f503
• cue/testdata: rename out/eval to out/evalalpha when appropriate by @rogpeppe in c76dc5a
• cue/build: fix stale identifier resolution across instances by @mvdan in dd7361a
• cmd/cue: add regression test for issue 4275 by @mvdan in 791e697
• encoding/yaml: improve ast.StructLit and ListLit positions by @cuematthew in cde471e
• cmd/cue: be more helpful when publishing a module without source by @mvdan in 3dfa50a
• encoding/jsonschema: remove net/url.Parse workaround for Go 1.26 by @mvdan in 6cce9bc

v0.16.0-alpha.2

Changes which may break some users are marked below with: ⚠️

Language

As a reminder, we have two ongoing language experiments since v0.15; a replacement for struct embedding and a rework of aliases. Please give these a try and report any issues or feedback!

The new try experiment

This experiment adds a try clause in comprehensions as well as the use of ? in field selectors. This addition to the language intends to provide a more concise syntax for handling optional fields without the risk of unintentionally swallowing errors.

You can try this experiment by following our how-to guide. For more information, see the proposal on GitHub and the spec change patch.

The new else comprehension clause

This change adds an optional else clause for CUE modules targetting the language version v0.16.0 or later. With this addition to the language, an if or for comprehension may be followed by an else clause which triggers when the comprehension produces zero values.

Note that this feature is not an experiment; it is available to any CUE module targetting the language version v0.16.0 or later.

You can try this feature by following our how-to guide. For more information, see the full patch which includes the changes to the spec, or read the pre-release version of the language spec.

Evaluator

A number of changes were made to improve support for using cue.Values concurrently; see Issue #2733 for more details and ongoing progress.

A number of panics and other bugs in the evaluator which were reported since v0.15.0 have been fixed; thank you to all who reported these.

cmd/cue

The global --verbose and --trace flags have been moved to the cue get go and cue trim commands respectively, as they were the only ones actually using those flags, and this could be confusing to users.

Fix a bug where loading ./...:pkgname could lead to loading directories with zero CUE files as instances, which could cause poor performance for CUE packages with multiple parent directories.

LSP server

Code Actions: two code actions are now provided, Add surrounding struct braces and Remove surrounding struct braces, which convert between

a: b: c

and

a: {
	b: c
}

with the cursor on b.

Initial LSP support for editing embedded JSON files. This feature provides completions and hover-docs when editing JSON files which are embedded into CUE via the @embed attribute. A teaser video is available on YouTube. Support for embedded YAML files will appear soon.

Several bug fixes, including better behaviour for files and directories with spaces; improvements for value aliases (foo: L=x); LSP rename now provides placeholder text.

See our Getting Started wiki page for instructions on how to set it up with your editor.

Please report any bugs or missing features you encounter via the Issue tracker or via the #lsp channels on Discord or Slack.

Encodings

Add support for encoding YAML tags like key: !Custom value by using CUE attributes like key: "value" @yaml(,tag="!Custom").

Standard library

The net package adds CompareIP to compare two IP addresses, which can be useful for computing with IP ranges.

The net/http package adds Serve as an experimental API to listen on a port and serve HTTP requests.

The tool/file package adds Symlink to create symbolic links.

Go API

cue/ast gains the NewPredeclared and Ident.IsPredeclared to mark and detect identifiers referencing predeclared names like error or int rather than fields which may shadow those names in the current scope.

⚠️ cue/token.Compare now sorts absolute paths before relative ones, to ensure consistent behavior between Unix-like systems and Windows.

⚠️ The long-deprecated and hidden cue.Instance.Eval method is now removed.

Full list of changes since v0.16.0-alpha.1

• internal/core/export: fix self-referential lets for recursive definitions by @mvdan in c257634
• internal/core/compile: avoid double error for invalid optional references by @mpvl in c1be2bb
• update all dependencies by @mvdan in 9fb0173
• internal/core/adt: add regression test for error() in pattern constraint keys by @mvdan in 50a0a5e
• internal/core/adt: fix structural cycle hang with braced selectors by @mvdan in 36702fd
• cmd/cue: add and unskip tests for invalid task type errors by @mvdan in db4afc1
• internal/core/dep: fix stack overflow on recursive definitions in dep analysis by @mvdan in 0b49a54
• internal/core/dep,internal/core/export: fix stack overflow on recursive definitions by @mvdan in d0e2ab6
• tools/flow: skip phantom tasks from eliminated conditional branches by @mvdan in 7fb912e
• encoding/gocode: fix test by @rogpeppe in 98ca6e3
• internal/core: remove import path to instance mapping by @rogpeppe in b3d9ffc
• doc/spec: use "custom errors" instead of "user errors" by @myitcv in baf8302
• internal/ci: explicitly set contents permission by @myitcv in 7cde504
• lsp/eval: Add support for try-clauses and optional path components by @cuematthew in 62de631
• cue/testdata: update stats for comprehensions/try.txtar by @mvdan in 20c1149
• internal/core/adt: implement try expressions by @mpvl in f2e8299
• cue/build: integrate identifier resolution into Complete by @mpvl in 1aeb33e
• lsp/fscache: ignore ASTs which have no absolute positions by @cuematthew in 2585b3b
• cue/ast,cue/ast/astutil: add NewPredeclared and IsPredeclared for builtin references by @mpvl in 8405422
• internal/core/adt: fix else clause duplication in comprehension field splitting by @mvdan in 40356ab
• cue/load: improve error for major-only version packages outside a module by @mvdan in 7675369
• cmd/cue/cmd: add test coverage for absolute packages with cue cmd by @mvdan in f5e266a
• encoding/yaml: add support for YAML tags via @yaml(,tag) attribute by @jonas-meyer in b1a58bd
• internal/astinternal: omit ILLEGAL tokens in debug print by @mpvl in 23736eb
• cue: clarify that Schema is only useful for Value.Subsume by @mvdan in bb18d7b
• lsp/cache: expand completion range of fields in json for double-quotes by @cuematthew in b1c63da
• all: start using "else" in comprehensions by @mvdan in 3f2f654
• tweak Claude's allow and deny settings further by @mvdan in ef6bb80
• internal/ci: disable checkout persist-credentials by default by @myitcv in 069eac9
• cue/load: do not load non-CUE directories as instances by @rogpeppe in a4d2a6f
• cue/load: add test case for non-package directories by @rogpeppe in 028411e
• cmd/cue: deflake cue_after test by @rogpeppe in 4504db0
• all: use reflect.TypeAssert in three more places by @mvdan in 58cbd0c
• cue/internal: Make ToFile optionally preserve StructLits by @cuematthew in ec3e289
• all: re-apply go fix -any=false ./... after Go version bump by @mvdan in 8579c46
• lsp/cache: completions must not return null items list by @cuematthew in 75ee97a
• internal/core/export: fix panic in relPathLength for BinaryExpr by @mvdan in 788eeed
• tools/fix: use ast.Predeclared to avoid shadowing in value alias conversion by @mvdan in 08a7ec3
• cue/ast,cue/ast/astutil: add Predeclared sentinel for builtin references by @mvdan in 42cc85f
• tools/fix: add tests for value alias conversion when "self" is in scope by @mvdan in 3dacb0c
• cue/ast/astutil: fix false positive in label expression check for let clauses by @mvdan in a93bcc1
• cmd/cue/cmd: add failing test for i...

v0.16.0-alpha.1

Changes which may break some users are marked below with: ⚠️

Language

As a reminder, we have two ongoing language experiments since v0.15; a replacement for struct embedding and a rework of aliases. Please give these a try and report any issues or feedback!

⚠️ The cmdreferencepkg global experiment is now stable, meaning that CUE_EXPERIMENT=cmdreferencepkg is always enabled.

#"""# is now accepted as a string literal quoting a double quote, ".

Multiline string literals now require a trailing newline, matching the language spec.

Evaluator

Performance

Further improve the use of caching in the typochecker algorithm; this provides speed-ups of up to 80% on some large projects.

Very large structs (tested with 20,000 fields) are up to 80% faster now, as we were repeating some work unnecessarily.

A great deal of effort has gone into reducing the allocations and memory usage across a number of projects. For some of these, memory usage is down by as much as 60%.

These improvements were possible thanks to our Unity service, letting us analyze CUE's performance and test for regressions on third party projects. Contact @mvdan on Discord, Slack, or via the Unity page to ensure that your project is included or you are running into slowness.

Other changes

Fix a regression introduced in v0.13 where the or built-in with literal arguments could stop behaving like a disjunction.

A number of panics and other bugs in the evaluator which were reported since v0.15.0 have been fixed; thank you to all who reported these.

cmd/cue

Add support for $DOCKER_AUTH_CONFIG to directly provide the contents of $DOCKER_CONFIG/config.json to authenticate with module registries, matching Docker's current behavior.

The --outfile flag now works when given non-regular files such as named pipes or sockets.

⚠️ cue mod publish no longer ignores sub-directories containing a go.mod file as if they were nested CUE modules; those are already skipped based on the presence of cue.mod.

⚠️ Using cue inside the cue.mod directory now fails consistently with a clear error message to not place CUE code there. Previously, some commands worked while others failed with confusing errors.

LSP server

Completions: a complete overhaul of how the LSP server suggests code completions. This solves the previous naïve implementation which would only make suggestions after a field name or path had been started. Now completions are available from within whitespace.

Embedded paths with mutual dependencies: embedded paths with multiple components (e.g. a.b.c) can in some cases only be fully resolved after the resolution of other embedded paths. The LSP server can now correctly handle these dependencies.

Document Symbols: the CUE LSP server now implements LSP "Document Symbols" functionality. This is often used by editors to provide light-weight breadcrumb navigation within a file.

Diagnostics: some preliminary diagnostics are now sent from the LSP server back to the editor. Initially this mainly indicates syntax errors in CUE files, but this can be extended in the future.

Bug fixes: many smaller bug fixes, addressing issues around imports, path resolution, formatting of standalone CUE files, amongst others.

See our Getting Started wiki page for instructions on how to set it up with your editor.

Please report any bugs or missing features you encounter via the Issue tracker or via the #lsp channels on Discord or Slack.

Encodings

cue get go now detects which Go packages use Kubernetes type semantics via // +k8s:openapi-gen=true and obeys the field annotations // +optional and // +nullable.

cue get go gains a --codec flag to configure the use and priority of Go struct field tags like json or yaml.

Fix a bug where cue get go could skip over fields whose type implements one of the supported marshaling interfaces.

Fix a few bugs where cue get go could result in invalid or failing CUE code.

JSON Schema's Config.OpenOnlyWhenExplicit option is now exposed for the CLI via the filetype tag jsonschema+openOnlyWhenExplicit.

JSON Schema now properly encodes hash references for better compatibility with other tools.

Standard library

The strconv package adds ParseNumber, like ParseInt or ParseFloat but allowing other CUE number strings such as 1Ki.

The net package adds InCIDR to test whether an IP is contained by a CIDR string.

The net package adds ParseCIDR to extract useful information from a CIDR string.

Go API

cue.Value.Decode now supports the new cue.Unmarshaler interface, allowing Go types to implement their own CUE value decoding logic via an UnmarshalCUE(cue.Value) error method.

The new cue.IsIncomplete function reports whether the given value is a CUE incomplete error.

⚠️ cue.Value.Decode now uses cue.IsIncomplete to not treat incomplete errors as fatal, allowing the decoding to continue.

Fix a bug where cue.Value.Decode could behave incorrectly when decoding a CUE null or incomplete value.

⚠️ The long-deprecated cue/ast.Node.Comments and cue/ast.Node.AddComment interface methods are now removed; use cue/ast.Comments and cue/ast.AddComment respectively.

⚠️ The long-deprecated and unused cue/parser.FromVersion and cue/parser.DeprecationError APIs are now removed.

Full list of changes since v0.15.0

• cue/load: error when loading packages from inside cue.mod by @mvdan in 52e0dde
• cmd/cue: add a testscript running commands inside cue.mod by @mvdan in 50aaf7e
• mod/modzip: check for cue.mod existence, not just directories by @mvdan in 8034cc1
• mod/modzip: check for cue.mod directories instead of go.mod files by @mvdan in 8957a36
• mod/modzip: add test for go.mod submodule detection by @mvdan in 3be6c26
• cue/format: simplify label replacement without astutil.Apply by @mvdan in fdc3f74
• cmd/cue: clarify the restrictions around @embed file paths by @mvdan in dc9a189
• .claude: allow more commands by @mvdan in 60b5bd9
• pkg/net: add ParseCIDR to extract CIDR information by @mvdan in ea83954
• pkg/net: add InCIDR to check if an IP is within a CIDR range by @mvdan in a3cffd4
• cue/format: fix comma placement for ellipsis with inline comments by @mvdan in 79305ff
• cue/format: add test for issue #4238 by @mvdan in 452fbae
• internal/core/adt: fix spurious error in ForClause.yield key binding by @mvdan in beae55b
• CLAUDE: discourage "go build" and add a set of "must follow" rules by @mvdan in 6301c2a
• encoding/json: correct positions of field labels from json by @cuematthew in 8c70d8d
• internal/cueexperiment: clarify the docs and update the ordering by @mvdan in 46dc5d7
• cmd/cue: appease gopls in gen_experiments_help.go by @mvdan in 79c8f3a
• internal/ci: bump Go and goreleaser for v0.16.0-alpha.1 by @mvdan in 29a1c5a
• update dependencies ahead of v0.16.0-alpha.1 by @mvdan in 14cf3bd
• doc/ref: clarify the relationship between exported and hidden identifiers by @mvdan in 367bc88
• internal/core/adt: avoid allocations in matchPattern by @mvdan in 523284f
• internal/core/adt: remove redundant updateConjunctInfo call by @mvdan in e52024b
• internal/core/convert: allocate vertices in ensureArcVertex better by @mvdan in e2b85a8
• pkg/math/bits: avoid an extra allocation per call by @mvdan in 9adb47a
• internal/core/convert: reuse singleton struct and list marker allocs by @mvdan in d06db86
• internal/core/adt: remove unused parameters in Vertex.AddStruct by @mvdan in a8d5eef
• internal/core/convert: avoid repeated OpContext.Env calls by @mvdan in 54e81b3
• internal/core/convert: avoid an allocation for "small" big.Int values by @mvdan in 72c8aac
• internal/core/adt: also use strings.ToValidUTF8 over x/text/encoding/unicode by @mvdan in b78f800
• internal/core/convert: use strings.ToValidUTF8 over x/text/encoding/unicode by @mvdan in 29aca5f...

v0.15.4

Evaluator

Fix a panic which could occur when using the error built-in with cyclic references.

Fix a panic which could occur when loading @experiment(aliasv2) syntax with an invalid alias name.

cmd/cue

Relax the cue login --token validation to allow future Central Registry token types.

Encodings

Fix a bug in the TOML decoder where nested arrays were causing incorrect "duplicate key" errors.

Full list of changes since v0.15.3

• internal/cueversion: bump LanguageVersion for v0.15.4 by @mvdan in 50c137c
• internal/ci: bump Go and goreleaser for v0.15.4 by @mvdan in 8e3eaa9
• cmd/cue: relax login --token prefix validation by @rustyx in d0bd478
• cue/ast/astutil: fix nil pointer dereference in postfix alias error by @mvdan in c5df0af
• internal/core/debug: fix stack overflow in error formatting by @mvdan in bf7a40d
• encoding/toml: correctly check for duplicate keys with arrays by @mvdan in 4a5fd52

v0.15.3

Evaluator

Fix a panic which could occur when using Expr after LookupPath on a cue.Value.

cmd/cue

Fix a panic which could occur when using cue cmd tasks referencing definitions.

Fix a panic which could occur when cue get go encountered a Go enum type with zero named values.

Encodings

Fix a bug in the TOML decoder where nested arrays were not being correctly mapped to CUE values.

Full list of changes since v0.15.1

• internal/ci: bump Go and goreleaser versions by @mvdan in 8a91fed
• cmd/cue: avoid panic in get go when an enum has zero named values by @mvdan in f544b9c
• encoding/toml: forget nested arrays when starting a new array element by @mvdan in 641c64a
• tools/flow: support task results when defined via definitions by @mvdan in 6d86ce6
• cmd/cue: add test case for issue #2633 by @mvdan in 3544f15
• internal/core/adt: check opID before inheriting parent reqSets by @mvdan in 3cb0e2d