# Miller command structure

## Overview

The outline of an invocation of Miller is:

* The program name `mlr`.
* Flags controlling input/output formatting, etc. (see the [flags reference](reference-main-flag-list.md)).
* One or more verbs -- such as `cut`, `sort`, etc. (see [verbs reference](reference-verbs.md)) -- chained together using [then](reference-main-then-chaining.md). You use these to transform your data.
* Zero or more filenames, with input taken from standard input if there are no filenames present. (You can place the filenames up front using `--from` or `--mfrom` as described on the [keystroke-savers page](keystroke-savers.md#file-names-up-front-including-from).)

For example, reading from a file:

GENMD-RUN-COMMAND
mlr --icsv --opprint head -n 2 then sort -f shape example.csv
GENMD-EOF

GENMD-RUN-COMMAND
mlr --from example.csv --icsv --opprint head -n 2 then sort -f shape
GENMD-EOF

Reading from standard input:

GENMD-RUN-COMMAND
cat example.csv | mlr --icsv --opprint head -n 2 then sort -f shape
GENMD-EOF

The rest of this reference section gives you full information on each of these parts of the command line.

See also the [Glossary](glossary.md) for more about terms such as
[record](glossary.md#record), [field](glossary.md#field),
[key](glossary.md#value), [streaming](glossary.md#streaming), and more.

## Verbs vs DSL

When you type `mlr {something} myfile.dat`, the `{something}` part is called a **verb**. It specifies how you want to transform your data. Most of the verbs are counterparts of built-in system tools like `cut` and `sort` -- but with file-format awareness, and giving you the ability to refer to fields by name.

The verbs `put` and `filter` are special in that they have a rich expression language (domain-specific language, or "DSL"). More information about them can be found on the [Intro to Miller's Programming Language page](miller-programming-language.md); see also the [DSL Reference](reference-dsl.md) for more details.

Here's a comparison of verbs and `put`/`filter` DSL expressions:

Example of using a verb for data processing:

GENMD-RUN-COMMAND
mlr stats1 -a sum -f x -g a data/small
GENMD-EOF

* Verbs are coded in Go
* They run a bit faster
* They take fewer keystrokes
* There's less to learn
* Their customization is limited to each verb's options

Example of doing the same thing using a DSL expression:

GENMD-RUN-COMMAND
mlr  put -q '@x_sum[$a] += $x; end{emit @x_sum, "a"}' data/small
GENMD-EOF

* You get to write your own expressions in Miller's programming language
* They run a bit slower
* They take more keystrokes
* There's more to learn
* They're highly customizable

## Exit codes

When you do `echo $?` immediately after running a Miller command (or any shell command), that's the _exit code_.

Miller's are as follows:

* 0 for normal exit.
* 1 if an error was encountered. There should be helpful text written to `stderr`; please [file a bug report](https://github.com/johnkerl/miller/issues/new), ideally with a reproducible scenario, if the text is either missing or unhelpful.
* 2 if there was a `panic` in the Go runtime -- you'll see lots of stack-trace lines. Please [file a bug report](https://github.com/johnkerl/miller/issues/new), ideally with a reproducible scenario, if you ever see this.
