Docs

CSV

sourceconditiontarget

✔

✔

✔

Description

The csv resource reads and writes a single cell in a CSV file. Rows are addressed by index and columns by header name through a Dasel selector, so .[0].firstname is the firstname column of the first data row.

source

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

condition

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

target

Writes the value into the cell. Files already holding it are reported as up to date and left untouched.

Parameters

NameTypeDescriptionRequired
commainteger[s][c][t] Comma specifies the csv separator character, default “,”
commentinteger[s][c][t] Comma specifies the csv comment character, default “#”
filestring[s][c][t] File specifies the csv file
filesarray[c][t] Files specifies a list of Json file to manipulate
keystring[s][c][t] Key specifies the csv query
querystring[s][c][t] Query allows to used advanced query. Override the parameter key
valuestring[s][c][t] Key specifies the csv value, default to source output
versionfilterobject[s]VersionFilter provides parameters to specify version pattern and its type like regex, semver, or just latest.
    kindstringspecifies the version kind such as semver, regex, or latest
    patternstringspecifies the version pattern according the version kind for semver, it is a semver constraint for regex, it is a regex pattern for time, it is a date format
    regexstringspecifies the regex pattern, used for regex/semver and regex/time. Output of the first capture group will be used.
    replaceallobjectreplaceAll applies a regex replacement to version strings before filtering. This is useful for transforming versions (e.g., curl-8_15_0 to curl-8.15.0) before regex extraction.
    strictbooleanstrict enforce strict versioning rule. Only used for semantic versioning at this time

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.

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

Separator and comment characters

comma and comment are Go runes, not strings. They must be given as the decimal code point of the character, so a semicolon-separated file is comma: 59, not comma: ";":

spec:
  file: data.csv
  key: .[0].version
  comma: 59      # ";" - 44 is "," (the default), 9 is a tab

Passing the character itself aborts the run before the pipeline starts:

error while cleaning config: failed to create resource csv: decoding failed due to the following error(s):
'Comma' expected type 'int32', got unconvertible type 'string'

comment works the same way and defaults to #, which is code point 35.

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 [0].firstname, not .[0].firstname.

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:

URL scheme is not supported for CSV target: "https://example.com/data.csv"

Limitations

Dasel rewrites the file from its parsed representation, so comments are dropped on any target that changes something - see tomwright/dasel#178. Formatting details such as quoting style are normalised the same way.

When that matters, drive the edit with the "File" resource and a matchpattern/replacepattern pair instead, which rewrites only the bytes that changed.

Example

# updatecli.yaml
name: CSV manipulation examples

sources:
  default:
    name: Basic get query
    kind: csv
    spec:
      file: pkg/plugins/resources/csv/testdata/data.csv
      key: .[0].firstname

conditions:
  single:
    name: Basic condition query
    kind: csv
    disablesourceinput: true
    spec:
      file: pkg/plugins/resources/csv/testdata/data.csv
      key: .[0].firstname
      value: John

targets:
  single:
    name: Basic target update
    kind: csv
    spec:
      file: pkg/plugins/resources/csv/testdata/data.csv
      key: .[1].firstname
      value: John

  multiple:
    name: Multiple target update
    kind: csv
    spec:
      files:
        - pkg/plugins/resources/csv/testdata/data1.csv
        - pkg/plugins/resources/csv/testdata/data2.csv
      query: .[*].firstname

Links

Last updated on July 30, 2026
Prev
Action
Next
Docker Digest