The Command Line

In this chapter you will learn:

• The eu command 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

eu [GLOBAL_OPTIONS] [SUBCOMMAND] [SUBCOMMAND_OPTIONS] [FILES...]

When no subcommand is given, run is assumed:

eu file.eu          # same as: eu run file.eu

Subcommands

Inputs

File Inputs

Specify one or more files to process:

eu data.yaml transform.eu

Inputs are merged left to right. Names from earlier inputs are available to later ones. The final input determines what is rendered.

stdin

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

Override the assumed format with a format@ prefix:

eu yaml@data.txt json@-

Named Inputs

Prefix with name= to make the input available under a name:

eu config=settings.yaml app.eu

In app.eu, the YAML content is available as config:

port: config.port

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 *.json

Outputs

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    # TOML
eu file.eu -x text    # Plain text

Output File

Write to a file (format inferred from extension):

eu data.eu -o output.json

Evaluands

The -e flag specifies an expression to evaluate:

eu -e '2 + 2'

4

When 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

Use -e for quick data exploration:

# Inspect a value
eu config.yaml -e 'database'

# Count items
eu data.json -e 'items count'

# Extract and transform
eu data.json -e 'items map(.name) reverse'

Targets

Declarations annotated with :target metadata can be selected for rendering:

# multi-output.eu
` { target: :summary }
summary: { count: items count }

` { target: :detail }
detail: items

List available targets:

eu list-targets multi-output.eu

Select a target:

eu -t summary multi-output.eu

A target named main is rendered by default. If no :main target exists, the entire unit is the target.

Passing Arguments

Arguments after -- are available via io.args:

eu -e 'io.args' -- hello world

- hello
- world

Use in scripts:

# greet.eu
name: io.args head-or("World")
greeting: "Hello, {name}!"

eu greet.eu -e greeting -- Alice

Hello, Alice!

Arguments are strings. Use num to convert:

numbers: io.args map(num)
total: numbers foldl(+, 0)

Environment Variables

Access environment variables through io.env:

home: io.env lookup-or(:HOME, "/tmp")
path: io.env lookup(:PATH)

Random Seed

By default, random numbers use system entropy. Use --seed for reproducible output:

eu --seed 42 template.eu

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.eu
eu --allow-io deploy.eu

This 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

Format eucalypt source files:

eu fmt file.eu              # print formatted to stdout
eu fmt --write file.eu      # format in place
eu fmt --check file.eu      # check (exit 1 if unformatted)
eu fmt --reformat file.eu   # full reformatting

Options:

• -w, --width <N> -- line width (default: 80)
• --indent <N> -- indent size (default: 2)

Debugging

Dumping Intermediate Representations

eu dump ast file.eu         # syntax tree
eu dump desugared file.eu   # core expression
eu dump stg file.eu         # compiled STG

Explaining Execution

eu explain file.eu          # show what would be executed

Statistics

eu -S file.eu               # print metrics to stderr

Suppressing the Prelude

The standard prelude is loaded automatically. Suppress it with -Q:

eu -Q file.eu

Warning: Without the prelude, even true, false, if, and basic operators are unavailable.

Version Assertions

Ensure a minimum eu version in source files:

_ : eu.requires(">=0.3.0")

Check the current version:

eu version

LSP Server

Start a Language Server Protocol server for editor integration:

eu lsp

Provides syntax error diagnostics and formatting support.

Key Concepts

• eu defaults to run when no subcommand is given
• Inputs are merged left to right; the final input determines output
• Named inputs (name=file) provide namespace isolation
• -e evaluates an expression against loaded inputs
• -t selects a named target for rendering
• -- passes arguments available via io.args
• eu fmt formats source files; eu test runs tests; eu lsp starts the language server