CLI Reference

Installation

Install with Go:

go install github.com/emlang-project/emlang@latest

Or download a precompiled binary from the releases page.

Usage

emlang <command> [flags] <file>

Available commands:

Global Flags

-c, --config

Path to the configuration file. See Configuration Reference for details on .emlang.yaml.

The configuration file is resolved in the following order:

1. The -c / --config flag value
2. The EMLANG_CONFIG environment variable
3. A .emlang.yaml file in the current working directory

If an explicit path (flag or environment variable) does not exist, the CLI returns an error. If the default path does not exist, an empty configuration is used.

emlang init

Create a .emlang.yaml configuration file with default values in the current directory.

Usage

emlang init

The command exits with an error if a .emlang.yaml file already exists in the current directory.

Examples

# Initialize a new config file
emlang init

emlang parse

Parse and display the structure of a YAML document. Useful for inspecting slices, elements, and tests.

Usage

emlang parse <file>

Arguments

Output

Displays a summary of the document including the number of slices, and for each slice: its name, element count, element details (type, swimlane, name, properties), and attached tests.

Examples

# Parse a file
emlang parse model.yaml

# Parse from stdin
cat model.yaml | emlang parse -

emlang lint

Analyze a YAML file for issues and best practices. Returns a list of warnings and errors with file location.

Usage

emlang lint <file>

Arguments

Output

If no issues are found:

model.yaml: OK (no issues found)

If issues are found, they are reported with file location, severity, and rule name:

model.yaml:25:5: warning: command should be followed by an event or exception [command-without-event]
model.yaml:30:5: warning: exception without preceding command [orphan-exception]

2 warnings

Rules can be ignored via the lint configuration.

Linting Rules

Examples

# Lint a file
emlang lint model.yaml

# Lint from stdin
cat model.yaml | emlang lint -

# Lint with a custom config
emlang -c custom-config.yaml lint model.yaml

emlang fmt

Format a YAML source file to canonical output. Sorts element properties and test names deterministically.

Usage

emlang fmt [flags] <file>

Arguments

Flags

The --keys flag priority is: flag > config > default (short).

Examples

# Format and print to stdout
emlang fmt model.yaml

# Format in-place
emlang fmt -w model.yaml

# Format with long keys
emlang fmt --keys long model.yaml

# Format from stdin
cat model.yaml | emlang fmt -

emlang diagram

Generate an HTML diagram from a YAML file. The diagram can be written to a file, printed to stdout, or served with live reload.

Usage

emlang diagram [flags] <file>

Arguments

Flags

Output modes

By default, the generated HTML is printed to stdout. Use -o to write to a file instead, or --serve to start a live-reload development server.

The --serve flag watches the input file for changes, regenerates the diagram automatically, and opens your browser. It cannot be combined with -o or stdin (-).

Diagram appearance can be customized via the diagram configuration.

Examples

# Generate and save to file
emlang diagram -o diagram.html model.yaml

# Output to stdout
emlang diagram model.yaml

# Live-reload server on default port (8274)
emlang diagram --serve model.yaml

# Live-reload server on custom port
emlang diagram --serve --port 3000 model.yaml

# Pipe from stdin
cat model.yaml | emlang diagram -o diagram.html -

emlang version

Print the CLI version and the specification version it implements.

Usage

emlang version

Output

emlang version 0.0.0 (spec 1.0.0)

Stdin Support

All content-consuming commands accept - as the file argument to read from stdin:

emlang parse -
emlang lint -
emlang fmt -
emlang diagram -
emlang diagram -o output.html -

The --serve flag in the diagram command does not support stdin, since it needs to watch the file for changes.

Exit Codes

Configuration

Emlang uses a .emlang.yaml file for project configuration. The CLI resolves the configuration file in the following order:

1. The -c flag: emlang -c path/to/config.yaml
2. The EMLANG_CONFIG environment variable
3. A .emlang.yaml file in the current working directory

See the Configuration Reference for the full list of options.