{#cli}
# Command-line interface

Running
`jaq` \[_OPTION_\]... \[_FILTER_\] \[_FILE_\]...
performs the following steps:

- Parse _FILTER_ as jq program; see [jq language](#corelang)
- For each _FILE_:

    - Parse _FILE_ to a stream of values
    - For each input value in the file:

        - Run _FILTER_ on the input value and print its output values
- If an uncaught error is encountered at any point, jaq stops.

For example, `jaq '.name?' persons.json`
parses the filter `.name?`, then
reads all values in `persons.json` one-by-one.
It then executes the filter `.name?` on each of the values and
prints the outputs of the filter as JSON.


## Input

If no _FILE_ is given, jaq reads from standard input.
jaq determines the format to parse a _FILE_ as follows:

- If [`--from`](#--from) _FORMAT_ is used, jaq uses that format.
- Otherwise, if _FILE_ has a file extension known by jaq, such as
  `.json`, `.yaml`, `.cbor`, `.toml`, `.xml`, `.csv`, `.tsv`
  jaq uses the corresponding format.
- Otherwise, jaq assumes JSON.

{#--from}
### `--from` _FORMAT_

Interpret all input files as _FORMAT_.
For example,
`jaq --from yaml . myfile.yml`
parses `myfile.yml` as YAML.
Possible values of _FORMAT_ include:
`raw`, `raw0`, `json`, `yaml`, `cbor`, `toml`, `xml`, `csv`, `tsv`.

jaq automatically chooses the corresponding input format for
files with the extensions
`.json`, `.yaml`, `.yml`, `.cbor`, `.toml`, `.xml`, `.xhtml`, `.csv`, `.tsv`.
That means that
`jaq --from cbor . myfile.cbor` is equivalent to
`jaq . myfile.cbor`.

::: Compatibility
`jq` does not have this option.
:::

{#--null-input}
### `-n`, `--null-input`

Feed `null` as input to the main program, ignoring any input files.
For example:

```
$ yes | jaq -n
null
```

This shows that this does indeed not read any input.

The inputs can still be obtained via the [`inputs`](#inputs) filter. For example:

```
$ yes true | jaq -n 'first(inputs)'
true
```

This can be useful to fold over all inputs with [`reduce` / `foreach`](#reduce-foreach).

{#--raw-input}
### `-R`, `--raw-input`

Read lines of the input as sequence of strings.
For example:

```
$ printf "Hello\nWorld" | jaq -R
"Hello"
"World"
```

When combined with [`--slurp`](#--slurp),
this yields the whole input as a single string.
For example:

```
$ printf "Hello\nWorld" | jaq -Rs
"Hello\nWorld"
```

See [`--rawfile`](#--rawfile).

This is equivalent to `--from raw`.

{#--raw-input0}
### `--raw-input0`

Read values like [`--raw-input`](#--raw-input), splitting by NUL (`\0`) instead of newlines.
For example:

```
$ printf "Hello\nWorld\0foo" | jaq --raw-input0
"Hello\nWorld"
"foo"
```

When combined with [`--slurp`](#--slurp),
this collects all inputs into an array.
For example:

```
$ printf "Hello\nWorld\0foo" | jaq -sc --raw-input0
["Hello\nWorld","foo"]
```

This option can be used to round-trip output from [`--raw-output0`](#--raw-output0):

```
$ printf '"some string\\nwith a newline" "another string"' | jaq --raw-output0 | jaq --raw-input0
"some string\nwith a newline"
"another string"
```

This is equivalent to `--from raw0`.

::: Compatibility
`jq` does not have this option.
:::

{#--slurp}
### `-s`, `--slurp`

Read all input values into one array (per file).
For example:

```
$ echo 1 2 3 | jaq
1
2
3
$ echo 1 2 3 | jaq -cs
[1,2,3]
```

When combined with [`--raw-input`](#--raw-input),
jaq reads the full input as a single string.
For example:

```
$ echo 1 2 3 | jaq -Rs
"1 2 3\n"
```

See [`--rawfile`](#--rawfile).

::: Compatibility
When multiple files are slurped in,
`jq` combines the inputs of all files into one single array, whereas
jaq yields an array for every file.
This is motivated by jaq's [`--in-place`](#--in-place) option,
which could not work with the behaviour implemented by `jq`.
The behaviour of `jq` can be approximated in jaq;
for example, to achieve the output of
`jq -s . a b`, you may use
`jaq -s . <(cat a b)`.
:::


## Output

{#--to}
### `--to` _FORMAT_

Print all output values in the given _FORMAT_.
Any _FORMAT_ accepted by [`--from`](#--from) can be used here.

Note that not every value can be printed in every format.
For example, TOML requires that the root value is an object, so
trying to print a non-object root value as TOML yields an error:

```
$ echo [] | jaq --to toml 2>/dev/null; echo $?
2
```

::: Compatibility
`jq` does not have this option.
:::

{#--compact-output}
### `-c`, `--compact-output`

Print JSON compactly, omitting whitespace. For example:

```
$ echo [1, 2, 3] | jaq -c
[1,2,3]
```

{#--raw-output}
### `-r`, `--raw-output`

Write (text and byte) strings without escaping them and without surrounding them with quotes.
For example:

```
$ printf '"Hello\\nWorld"' | jaq -r
Hello
World
$ printf '"Hello\\nWorld"' | jaq
"Hello\nWorld"
```

This does not impact strings contained inside other values, i.e. arrays and objects.
For example:

```
$ printf '["Hello\\nWorld"]' | jaq -rc
["Hello\nWorld"]
```

This is equivalent to `--to raw`.

{#--raw-output0}
### `--raw-output0`

Output values like [`--raw-output`](#--raw-output), terminating them with NUL (`\0`) instead of LF (`\n`).

```
$ printf '"some string\\nwith a newline" true' | jaq --raw-output0 | jaq -s --raw-input tobytes
b"some string\nwith a newline\x00true\x00"
```

Any output value that is a string containing NUL produces an error.
Note that this does not apply to strings contained in an array or an object.

```
$ printf '"string with NUL \\u0000"' | jaq --raw-output0 2>/dev/null; echo $?
2
```

This is equivalent to `--to raw0`.

{#--join-output}
### `-j`, `--join-output`

Do not print a newline after each value.
For example:

```
$ echo true false | jaq -j && echo " (no new line at end)"
truefalse (no new line at end)
```

This is particularly useful in combination with `--raw-output` (`-r`); for example:

```
$ printf '"Hello" " " "World" "\\n"' | jaq -jr
Hello World
```

{#--in-place}
### `-i`, `--in-place`

Overwrite input file with its output.
For example:

```
$ echo 1 > tmp.json && jaq -i '.+1' tmp.json && cat tmp.json && rm tmp.json
2
```

This reads the file `tmp.json` and
overwrites it with the output of the filter `.+1`.
Note that the input file is overwritten only
once there is no more output and
if there has not been any error.

::: Compatibility
`jq` does not have this option.
:::

::: Advanced
By default, this option disables colored output.
However, when forcing colors with [`-C`](#--color-output), jaq respects this wish:

```
$ echo [] > tmp.json
$ jaq -i    . tmp.json && jaq -R tobytes tmp.json
b"[]"
$ jaq -i -C . tmp.json && jaq -R tobytes tmp.json
b"\x1b[1;39m[\x1b[0m\x1b[1;39m]\x1b[0m"
$ rm tmp.json
```
:::

{#--sort-keys}
### `-S`, `--sort-keys`

Print objects sorted by their keys.
For example:

```
$ echo '{"b": {"d": 3, "c": 2}, "a": 1}' | jaq -cS
{"a":1,"b":{"c":2,"d":3}}
$ echo '{"b": {"d": 3, "c": 2}, "a": 1}' | jaq -c
{"b":{"d":3,"c":2},"a":1}
```

{#--color-output}
### `-C`, `--color-output`

Always color output, even if jaq does not print to a terminal.
For example:

```
$ echo {} | jaq -C | jaq --from raw tobytes
b"\x1b[1;39m{\x1b[0m\x1b[1;39m}\x1b[0m"
$ echo {} | jaq    | jaq --from raw tobytes
b"{}"
```

(Here, `jaq --from raw tobytes` prints a byte representation of its input,
which contains ANSI color sequences in case of `-C`.)

{#--monochrome-output}
### `-M`, `--monochrome-output`

Do not color output.

### `--tab`

Use tabs for indentation rather than spaces.

For example:

```
$ echo [1, [2]] | jaq --tab | jaq -Rs
"[\n\t1,\n\t[\n\t\t2\n\t]\n]\n"
$ echo [1, [2]] | jaq       | jaq -Rs
"[\n  1,\n  [\n    2\n  ]\n]\n"
```

{#--indent}
### `--indent` _N_

Use _N_ spaces for indentation (default: 2).

### `NO_COLOR`

If the environment variable `NO_COLOR` is set to a non-empty value, then
jaq prints no colors, unless the [`-C`](#--color-output) flag is used.

### `JQ_COLORS`

The environment variable `JQ_COLORS` is a colon-separated list, where
each entry gives a style to be used for printing some type of values.
The entries of `JQ_COLORS` are mapped in the following order to types of values:

- `null`
- `false`
- `true`
- numbers
- strings
- arrays
- objects
- object keys

If `JQ_COLORS` is not set, then it is assumed to be `90:39:39:39:32:1;39:1;39:1;34`.
That means that by default:

- `null` has the style `90` (gray foreground color).
- `false`/`true`/numbers have the style `39` (default foreground color).
- Strings have the style `32` (green foreground color).
- Arrays/objects have the style `1;39` (bold and default foreground color).
- Object keys have the style `1;34` (bold and blue foreground color).

Each non-empty entry of `JQ_COLORS`, such as `90` or `1;39`, is turned into a
["Select Graphic Rendition"](https://en.wikipedia.org/wiki/ANSI_escape_code#Select_Graphic_Rendition_parameters)
(SGR) control sequence.
For example:

- `32`   is turned into `\x1b[32m`.
- `1;39` is turned into `\x1b[1;39m`.

::: Compatibility
`jq` also considers a style for object keys, after objects.
However, in jaq, object keys can be any kind of values, so jaq ignores this.
On the other hand, jaq does not allow changing the color of byte strings,
because jq does not provide any facilities to do that.
:::

## Compilation

If no _FILTER_ is given, jaq uses `.` (the [identity filter](#identity)) as filter.

When passing filters directly as _FILTER_ argument on the command-line,
care has to be taken to properly escape the filter.
How to do this depends from platform to platform, but on Unixoid systems,
surrounding the filter with single quotes (`'`) and
replacing occurrences of `'` in filters by `'\''` suffices.
For example, to run the filter `"'"` that
produces a string containing a single quote, you can use:

```
$ jaq -n '"'\''"'
"'"
```

Running filters that start with the [negation operator](#negation),
such as `jaq '-1'`, fails because `-` is interpreted as
start of a command-line switch rather than negation.
You can remedy this by using `--` or by surrounding the filter in parentheses:

```
$ jaq -n -- '-1'
-1
$ jaq -n '(-1)'
-1
```

{#--from-file}
### `-f`, `--from-file`

Read filter from a file given by filter argument.

With this option, jaq interprets the _FILTER_ argument as
name of a file containing the filter.
Note that the file name may not directly succeed this option.
For example:

```
$ echo '2 * 21' > tmp.jq && jaq --from-file -n tmp.jq && rm tmp.jq
42
```

{#--library-path}
### `-L`, `--library-path` _DIR_

Search for [modules](#modules) and data in given directory.

jaq searches for modules and data in a set of directories called "search paths".
Using `--library-path` adds a new directory to the global search paths.

For example,
`jaq -L . -L .. 'include "script"; foo'`
looks for `script.jq` first in the current directory, then in the parent directory.

If `--library-path` is not given, the following global search paths are used:

- `~/.jq`
- `$ORIGIN/../lib/jq`
- `$ORIGIN/../lib`

See the [modules](#modules) section for more details.


## Variables

{#--arg}
### `--arg` _A_ _V_

Set variable `$A` to string _V_.

For example:

```
$ jaq --arg name "John Doe" -n '"Welcome, " + $name'
"Welcome, John Doe"
```

{#--argjson}
### `--argjson` _A_ _V_

Set variable `$A` to JSON value _V_.

For example:

```
$ jaq --argjson song '{"name": "One of Us", "artist": "ABBA", "year": 1981}' -n \
  '"Currently playing: \($song.name) (\($song.year))"'
"Currently playing: One of Us (1981)"
```

If _V_ contains more than a single value, e.g. `1 2`, then jaq yields an error.

{#--slurpfile}
### `--slurpfile` _A_ _F_

Set variable `$A` to array containing the JSON values in file _F_.

For example:

```
$ echo 1 2 3 > tmp.json && jaq --slurpfile xs tmp.json -cn '$xs' && rm tmp.json
[1,2,3]
```

{#--rawfile}
### `--rawfile` _A_ _F_

Set variable `$A` to string containing the contents of file _F_.

jaq tries to load the file via memory mapping,
taking constant time and allowing to load files that do not fit into memory.
If this fails, jaq loads the file regularly, taking linear time.
This is also what happens when using
`-Rs` ([--raw-input](#--raw-input) and [--slurp](#--slurp))
to load a file (as opposed to standard input).

::: Compatibility
Unlike `jq`, jaq does not verify that the file is valid UTF-8.
That permits loading arbitrary binary files;
these can be processed as byte strings via [`tobytes`](#tobytes).
:::

### `--args`

Collect remaining positional arguments into `$ARGS.positional`.

If this option is given, then all further arguments that
would have been interpreted as input files are
instead collected into an array at `$ARGS.positional`.

For example:

```
$ touch tmp.json && jaq '$ARGS.positional' tmp.json --args foo -nc bar -- baz -j qux && rm tmp.json
["foo","bar","baz","-j","qux"]
```

Note that here, `tmp.json` and `-nc` are *not* collected into the array ---
the former because it comes *before* `--args`, and
the latter because it would not have been interpreted as input file.
However, `-j` is collected into the array because it comes after `--`,
which leads every argument after it to be interpreted as input file.


## Miscellanea

{#--exit-status}
### `-e`, `--exit-status`

Use the last output value as exit status code.

This enables the use of the exit codes 1 and 4, which are not used otherwise.

jaq uses the following exit codes:

- 0: No errors.
- 1: The last output value is `false` or `null`.
- 2: I/O or CLI error, e.g. file not found or unknown CLI option.
- 3: Filter parse/compilation error.
- 4: The filter did not yield any output.
- 5: Any other error, e.g. call to the filter [`error`](#error).

The filters [`halt`](#halt) and [`halt_error`](#halt_error)
can be used to exit jaq with arbitrary exit codes.

For example:

```
$ jaq -n empty; echo $?
0
$ jaq -n false >/dev/null; echo $?
0
$ jaq -en false >/dev/null; echo $?
1
$ jaq . does_not_exist.json 2>/dev/null; echo $?
2
$ jaq --foo 2>/dev/null; echo $?
2
$ jaq '+' 2>/dev/null; echo $?
3
$ jaq -en empty; echo $?
4
$ jaq -n error 2>/dev/null; echo $?
5
$ jaq -n 'halt(9)'; echo $?
9
```


{#--help}
### `-h`, `--help`

Print summary of CLI options.

{#--version}
### `-V`, `--version`

Print jaq version.


{#unsupported-cli}
## Unsupported

The following command-line options are supported by `jq`, but not by jaq:

- `--ascii-output`, `-a`
- `--raw-output0`
- `--unbuffered`
- `--stream`
- `--stream-errors`
- `--seq`
- `--jsonargs`
