Run expressions over input data

run parses and binds an expression as open once, then evaluates it for every generated input row.

Each compact result is written on its own line. Processing stops at the first source or evaluation failure. Results use Expressif’s raw display syntax by default. Pass --output json to serialize each result as a valid JSON value; --raw is a shortcut for the default --output raw mode. Use --output-style pretty to render structured results across lines indented with two spaces per nesting level; --output-style compact is the default. Output format and style are independent, so --output json --pretty --indent 2 produces indented JSON. Configured value types whose complete compact form fits within the preferred line width remain inline in pretty raw and JSON output. The defaults select tuples and 80 characters. Use the shared or run-specific inline-types and preferred-line-width configuration settings to change that policy.

flowchart LR
    A[Input rows] --> B[Parse + bind expression once]
    B --> C[Evaluate for each row]
    C --> D[One output line per row]

Choose an input mode

Mode	Row behavior	Compatibility
--input / -i	Each occurrence supplies exactly one row.	Can be combined with --batch.
--batch	Each direct element of one enumerable becomes a row.	Can be combined with --input.
--source / -s	Rows are read from a CSV, JSON, or source-expression file.	Cannot be combined with --input or --batch.
--format	Overrides source format detection with csv or json.	Requires --source.
--output	Serializes results as raw or json.	Defaults to raw.
--raw	Shortcut for --output raw.	Mutually exclusive with --output.
--output-style	Formats results as compact or pretty.	Defaults to compact.
--pretty	Shortcut for --output-style pretty.	Mutually exclusive with other style selectors.
--compact	Shortcut for --output-style compact.	Mutually exclusive with other style selectors.
--indent	Uses 0–8 spaces or tab for pretty indentation.	Requires pretty output; defaults to 2 spaces.

At least one input mode is required.

Supply repeated inputs

expressif run 'add(1)' --input 1 --input '{2, 3}' --input 4

This creates three rows: the number 1, the array {2, 3}, and the number 4. An array supplied with --input remains one row; it is not flattened.

Expand an enumerable batch

expressif run 'add(1)' --batch '{1, 2, 3}'

2
3
4

--batch can appear only once. Its value must be enumerable and cannot be text or a record. Only the direct elements become rows, so nested arrays remain intact.

When repeated inputs and a batch are combined, --input rows are evaluated before the batch elements.

Run over a CSV file

expressif run '.name | upper' --source people.csv

The source format is normally inferred from the filename. Use --format csv or --format json when the filename has no recognized extension or when its extension does not describe its contents. An explicit format takes precedence over the extension:

expressif run '.name | upper' --source people.data --format json

Without --format, recognized source extensions are .csv, .json, .expr, and .expressif. Other extensions produce an error explaining how to select a format.

The .csv extension is matched without regard to case. By default, the first row supplies field names and every following row becomes a record.

Header names must be non-empty and unique without regard to case. Every data row must have the expected number of fields. Empty text remains empty text, while database DBNull values become Expressif null values.

Set header=false for a headerless file:

expressif run '.column1 | upper' --source people.csv \
  --source-option 'header=false'

Generated field names are column1, column2, and so on.

Project a single column as a scalar

By default, a tabular row is a record. --scalar projects the only column directly:

expressif run 'absolute | add(1)' --source values.csv --scalar

The source must expose exactly one column.

Configure the CSV profile

Repeat --source-option with name=value assignments. Option names are case-sensitive and values use Expressif literal syntax.

expressif run '.name | upper' --source people.csv \
  --source-option 'delimiter=";"' \
  --source-option 'header=true'

Common options include:

Option	Value	Purpose
delimiter	one character	Set the field separator.
quote-char	one character or null	Set or disable the quote character.
escape-char	one character or null	Set an explicit escape character.
header	boolean	Indicate whether header rows exist.
header-rows	non-empty array of one-based integers	Select physical rows used to construct headers.
comment-char	one character or null	Mark comment rows.
comment-rows	non-empty array of one-based integers	Ignore selected physical rows.
skip-initial-space	boolean	Control whitespace after delimiters.
array-delimiter	one character or null	Split embedded array values.

Additional profile options are visible with expressif run --help. Unknown options, malformed assignments, wrong value types, and incompatible combinations are rejected before evaluation.

Run over an Expressif source

A non-CSV source file is treated as an Expressif expression:

expressif run 'absolute | add(1)' --source values.expr

The CLI reads the file as strict UTF-8, parses and binds it as a closed expression, evaluates it once, and uses each direct element of the resulting enumerable as a row. A null, text, record, or other scalar result is not a valid row source.

CSV source options and --scalar do not apply to non-tabular enumerable sources.