Updatecli
Docs

TOML

sourceconditiontarget

✔

✔

✔

Description

The toml resource reads and writes a single value in a TOML document, addressed by a Dasel selector.

source

Reads one value out of one file. Only a single file is accepted.

condition

Compares the value to value, or to the source output when value is unset.

target

Writes the value at the given key. Files already holding it are reported as up to date and left untouched.

Parameters

NameTypeDescriptionRequired
createmissingkeyboolean

“createmissingkey” creates the key when the toml file does not hold it yet.

compatible:

  • target

default: false

remark:

  • when false, a missing key raises an error.
  • only supported with “key”.
  • not supported by the “dasel/v3” engine, which cannot create missing keys.
enginestring

“engine” defines the engine used to manipulate the toml file.

compatible:

  • source
  • condition
  • target

default: dasel/v1

remark:

  • accepted values are “dasel/v1”, “dasel/v2”, “dasel/v3” and “dasel”.
  • “dasel” selects the latest dasel engine, currently “dasel/v3”.
  • “dasel/v1” and “dasel/v2” are deprecated in favor of “dasel/v3”.

example:

  • engine: dasel/v3
filestring

“file” defines the path of the toml file to use.

compatible:

  • source
  • condition
  • target

remark:

  • “file” and “files” are mutually exclusive.
  • the schemes “https://”, “http://” and “file://” are supported in a source or a condition.

example:

  • file: Cargo.toml
filesarray

“files” defines the list of toml file paths to use.

compatible:

  • condition
  • target

remark:

  • “file” and “files” are mutually exclusive.
  • the schemes “https://”, “http://” and “file://” are supported in a condition.
keystring

“key” defines the toml key path to use.

compatible:

  • source
  • condition
  • target

remark:

  • “key” or “query” is required.
  • “key” accepts a dasel query matching the selected engine, more information on https://github.com/tomwright/dasel

example:

  • key: package.version
querystring

“query” defines an advanced dasel v1 query returning several values.

compatible:

  • source
  • condition
  • target

remark:

  • “key” or “query” is required.
  • “query” is only used by the “dasel/v1” engine. The engines “dasel/v2” and “dasel/v3” require “key” instead.
  • with the “dasel/v1” engine, “query” takes precedence over “key”.
  • in a source, “query” and “versionfilter” must be used together.
  • “query” accepts a dasel query, more information on https://github.com/tomwright/dasel
valuestring

“value” defines the value associated with the toml key.

compatible:

  • condition
  • target

default: the output of the associated source.

versionfilterobject

“versionfilter” defines the version pattern and its kind, such as “regex”, “semver” or “latest”.

compatible:

  • source

remark:

  • with the “dasel/v1” engine, “versionfilter” and “query” must be used together.
  • more information on https://www.updatecli.io/docs/core/versionfilter/
    kindstring

“kind” defines the versioning scheme used to select a version.

default: latest

remark:

  • accepted values are “latest”, “semver”, “regex”, “regex/semver”, “time”, “regex/time”, “lex” and “pep440”.
  • “latest” returns the last version of the list.
  • “lex” sorts the versions lexicographically and returns the last one.
  • “pep440” follows https://peps.python.org/pep-0440/

example:

  • kind: semver
    patternstring

“pattern” defines the version pattern, according to “kind”.

default:

  • latest: “latest”
  • semver and pep440: “*”
  • regex: “.*”
  • time and regex/time: “2006-01-02”

remark:

  • for “latest”, “latest” returns the last version, any other value must match a version exactly.
  • for “semver” and “regex/semver”, it is a semantic versioning constraint.
  • for “pep440”, it is a pep440 version specifier.
  • for “regex”, it is a regular expression.
  • for “time” and “regex/time”, it is a Go date layout.
  • ignored by “lex”.

example:

  • pattern: ~1.2
  • pattern: “>=1.0.0 <2.0.0”
  • pattern: ^v\d+.\d+.\d+$
    regexstring

“regex” defines the regular expression extracting the version from each entry.

remark:

  • only used by the kinds “regex/semver” and “regex/time”.
  • the value of the first capture group is used as the version.

example:

  • regex: ^v(\d+.\d+.\d+)$
    replaceallobject

“replaceall” applies a regular expression replacement to each version before filtering.

remark:

  • only used by the kinds “regex”, “regex/semver” and “regex/time”.
  • the replacement runs before “pattern” or “regex” is evaluated.

example:

replaceall:
  pattern: "_"
  replacement: "."

turns “curl-8_15_0” into “curl-8.15.0”.

    strictboolean

“strict” enforces strict semantic versioning rules when parsing versions.

default: false

remark:

  • only used by the kinds “semver” and “regex/semver”.

file or files is mandatory, as is key or query; missing either aborts the run with wrong spec content. file and files are mutually exclusive.

createmissingkey

Target only. Creates the key when it does not exist instead of failing. Only works together with key, and not with the dasel/v3 engine (that combination is rejected at validation time with engine "dasel/v3" does not support the parameter "createmissingkey", because the v3 API resolves the key before setting a value).

Note
multiple is deprecated and hidden from the table above. Use a selector returning several values instead.

Engines

engine selects which version of Dasel parses the file, and the selector syntax is not portable between versions.

ValueBehaviour

dasel/v1

Default when engine is unset. Deprecated - every run logs a warning.

dasel/v2

Deprecated - every run logs a warning.

dasel/v3

Current engine. Rejects the leading dot: use package.version, not .package.version. Incompatible with createmissingkey.

dasel

Alias resolving to the latest engine, currently dasel/v3.

Warning
query is a dasel/v1 parameter. On dasel/v2 and dasel/v3, a query without a key fails validation with engine "dasel/v3" requires the parameter "key" over "query". On dasel/v1, query is the multi-value form and must be paired with versionfilter in a source.

Remote files

file accepts https://, http:// and file:// for a source and a condition. A target refuses a URL outright with URL scheme is not supported for TOML target.

Limitations

Dasel rewrites the file from its parsed representation, so comments are dropped on any target that changes something - see tomwright/dasel#178. This bites hardest on hand-maintained files such as netlify.toml or Cargo.toml.

The workaround is to drive the edit with the "File" resource, matching the line with a regular expression so only those bytes are rewritten:

# updatecli.yaml
name: Fallback example with TOML

sources:
    hugo:
        name: Get latest HUGO version
        kind: githubrelease
        transformers:
            - trimprefix: v
        spec:
            owner: gohugoio
            repository: hugo
            token: '{{ requiredEnv "UPDATECLI_GITHUB_TOKEN" }}'
            username: '{{ requiredEnv "UPDATECLI_GITHUB_ACTOR" }}'

targets:
    netlify:
        name: Update Hugo version used on Netlify
        kind: file
        spec:
            file: netlify.toml
            matchpattern: HUGO_VERSION = "(.*)"
            replacepattern: HUGO_VERSION = "{{ source "hugo" }}"
        scmid: default
        sourceid: hugo

Example

# updatecli.yaml
name: Basic TOML Example

sources:
  local:
    name: Get value from toml
    kind: toml
    spec:
      file: pkg/plugins/resources/toml/testdata/data.toml
      key: .owner.firstName

conditions:
  local:
    name: Test value from toml
    kind: toml
    spec:
      file: pkg/plugins/resources/toml/testdata/data.toml
      key: .owner.firstName

targets:
  local:
    name: Ensure owner.firstName is set to John
    kind: toml
    spec:
      file: pkg/plugins/resources/toml/testdata/data.toml
      key: .owner.firstName
      value: John

Links

Last updated on August 2, 2026
Prev
Terraform Registry
Next
Tool Versions