The Command Line
In this chapter you will learn:
- The
eucommand structure and subcommands - How to specify inputs, outputs, and evaluands
- How to use targets, arguments, and environment variables
- How to use the formatter and other tools
Command Structure
Section titled “Command Structure”eu [GLOBAL_OPTIONS] [SUBCOMMAND] [SUBCOMMAND_OPTIONS] [FILES...]When no subcommand is given, run is assumed:
eu file.eu # same as: eu run file.euSubcommands
Section titled “Subcommands”| Command | Description |
|---|---|
run |
Evaluate and render (default) |
test |
Run embedded tests |
dump |
Dump intermediate representations |
version |
Show version information |
explain |
Show what would be executed |
list-targets |
List export targets |
fmt |
Format source files |
lsp |
Start the Language Server Protocol server |
check |
Check type annotations without evaluating |
doc |
Extract documentation from source |
Inputs
Section titled “Inputs”File Inputs
Section titled “File Inputs”Specify one or more files to process:
eu data.yaml transform.euInputs are merged left to right. Names from earlier inputs are available to later ones. The final input determines what is rendered.
Use - to read from stdin, or simply pipe data when no files are
specified:
curl -s https://api.example.com/data | eu -e 'items count'Format Override
Section titled “Format Override”Override the assumed format with a format@ prefix:
eu yaml@data.txt json@-Named Inputs
Section titled “Named Inputs”Prefix with name= to make the input available under a name:
eu config=settings.yaml app.euIn app.eu, the YAML content is available as config:
port: config.portCollecting Inputs
Section titled “Collecting Inputs”Gather multiple files into a named collection:
eu -c data *.json -e 'data map(.name)'Add -N to key by filename:
eu -c data -N *.jsonOutputs
Section titled “Outputs”Format
Section titled “Format”Output defaults to YAML. Common options:
eu file.eu # YAML (default)eu file.eu -j # JSON (shortcut)eu file.eu -x json # JSON (explicit)eu file.eu -x toml # TOMLeu file.eu -x text # Plain textOutput File
Section titled “Output File”Write to a file (format inferred from extension):
eu data.eu -o output.jsonEvaluands
Section titled “Evaluands”The -e flag specifies an expression to evaluate:
eu -e '2 + 2'4When combined with file inputs, the evaluand has access to all loaded names:
eu data.yaml -e 'users filter(.active) count'Multiple -e flags are allowed; the last one determines the output.
Quick Expressions
Section titled “Quick Expressions”Use -e for quick data exploration:
# Inspect a valueeu config.yaml -e 'database'
# Count itemseu data.json -e 'items count'
# Extract and transformeu data.json -e 'items map(.name) reverse'Targets
Section titled “Targets”Declarations annotated with :target metadata can be selected for
rendering:
` { target: :summary }summary: { count: items count }
` { target: :detail }detail: itemsList available targets:
eu list-targets multi-output.euSelect a target:
eu -t summary multi-output.euA target named main is rendered by default. If no :main target
exists, the entire unit is the target.
Passing Arguments
Section titled “Passing Arguments”Arguments after -- are available via io.args:
eu -e 'io.args' -- hello world- hello- worldUse in scripts:
name: io.args head-or("World")greeting: "Hello, {name}!"eu greet.eu -e greeting -- AliceHello, Alice!Arguments are strings. Use num to convert:
numbers: io.args map(num)total: numbers foldl(+, 0)Environment Variables
Section titled “Environment Variables”Access environment variables through io.env:
home: io.env lookup-or(:HOME, "/tmp")path: io.env lookup(:PATH)Random Seed
Section titled “Random Seed”By default, random numbers use system entropy. Use --seed for
reproducible output:
eu --seed 42 template.euIO Permission
Section titled “IO Permission”Programs that use the IO monad (io.shell, io.exec, and friends)
must be run with -I/--allow-io, or evaluation fails with a
permission error before any shell command runs:
eu -I deploy.eueu --allow-io deploy.euThis is a safety gate — code that shells out is not allowed to run by accident. See IO and Shell Commands for the full IO monad guide.
The Formatter
Section titled “The Formatter”Format eucalypt source files:
eu fmt file.eu # print formatted to stdouteu fmt --write file.eu # format in placeeu fmt --check file.eu # check (exit 1 if unformatted)eu fmt --reformat file.eu # full reformattingOptions:
-w, --width <N>– line width (default: 80)--indent <N>– indent size (default: 2)
Debugging
Section titled “Debugging”Dumping Intermediate Representations
Section titled “Dumping Intermediate Representations”eu dump ast file.eu # syntax treeeu dump desugared file.eu # core expressioneu dump stg file.eu # compiled STGExplaining Execution
Section titled “Explaining Execution”eu explain file.eu # show what would be executedStatistics
Section titled “Statistics”eu -S file.eu # print metrics to stderrSuppressing the Prelude
Section titled “Suppressing the Prelude”The standard prelude is loaded automatically. Suppress it with -Q:
eu -Q file.euWarning: Without the prelude, even
true,false,if, and basic operators are unavailable.
Version Assertions
Section titled “Version Assertions”Ensure a minimum eu version in source files:
_ : eu.requires(">=0.3.0")Check the current version:
eu versionLSP Server
Section titled “LSP Server”Start a Language Server Protocol server for editor integration:
eu lspProvides syntax error diagnostics and formatting support.
Key Concepts
Section titled “Key Concepts”eudefaults torunwhen no subcommand is given- Inputs are merged left to right; the final input determines output
- Named inputs (
name=file) provide namespace isolation -eevaluates an expression against loaded inputs-tselects a named target for rendering--passes arguments available viaio.argseu fmtformats source files;eu testruns tests;eu lspstarts the language server