---
description: Reference for Jawk command-line options and runtime operands.
date_published: 2026-05-13
date_modified: 2026-05-13
canonical_url: https://jawk.io/cli-reference.html
---

# CLI Reference

On this Page

- [Invocation Shape](#invocation-shape)
- [Option Groups](#option-groups)
- [Execution Notes](#execution-notes)
- [Tuple Serialization Compatibility](#tuple-serialization-compatibility)
- [See Also](#see-also)

This page documents the CLI surface implemented by [Cli](apidocs/io/jawk/Cli.html)[1]. It focuses on the actual parser-backed options in the current codebase rather than historical flags from older Jawk documentation.

** Caution

Precompiled tuples loaded with `-L` use Java serialization and are version-sensitive. If Jawk reports that a tuples file is incompatible, recompile it with the current Jawk version instead of trying to reuse the old file.

## [Invocation Shape](#invocation-shape)

The common command shape is:

```shell
java -jar jawk-6.4.00-standalone.jar [options] [script] [name=value | input_filename]...
```

The extension listing mode is separate:

```shell
java -jar jawk-6.4.00-standalone.jar --list-ext
```

## [Option Groups](#option-groups)

Script selection

- `script` is the inline AWK program used when you do not pass `-f` or `-L`.
- `-f <filename>` reads a script from a file. You can repeat `-f` to combine multiple script sources.
- `-L <filename>` loads previously serialized `AwkTuples` instead of compiling source now.
- `--persist <filename>` loads retained user-defined globals from a serialized state file before execution and writes them back after the run finishes.
- `-K <filename>` compiles the current script sources to a tuples file and exits without executing the script.

Input and `ARGV`

- Remaining operands after the script are exposed through `ARGV` and `ARGC`.
- An operand without `=` is treated as an input filename.
- An operand containing `=` is treated as an AWK-style file-list assignment that applies before the next input file is consumed.
- Use `-v name=value` instead when the variable must exist before `BEGIN`.

Variables and formatting

- `-v <name=value>` assigns a variable before execution begins.
- `-F <fs>` sets the initial field separator.
- `-r` disables Jawk's default trapping of `IllegalFormatException` for `printf` and `sprintf`.
- `--locale <locale>` sets the locale through `Locale.forLanguageTag(...)`.
- `-t` keeps associative array keys sorted.
- `--posix` enforces POSIX-oriented compile-time behavior such as disabling gawk-style nested arrays.
- `JAWK_PERSISTENT_MEMORY` can also point at the persistent-memory file when you do not want to pass `--persist` explicitly. `--persist` wins when both are present.

Extensions and sandbox

- `-l <extension>` or `--load <extension>` loads an extension by registered identifier, simple class name, or fully qualified class name.
- `--list-ext` prints the identifiers currently registered in `ExtensionRegistry` and exits. It must be used by itself.
- `-S` or `--sandbox` compiles and runs the script with sandbox restrictions enabled.

Inspection and compilation

- `--dump-syntax` prints the parsed abstract syntax tree and skips execution.
- `--dump-intermediate` prints the tuple stream and skips execution.
- `-s` or `--no-optimize` disables tuple optimization during compilation.
- `--profile` executes the script with runtime profiling enabled and prints tuple and function timing statistics to stderr.
- `--profile=<filename>` writes the same profiling report to the specified file instead of stderr.

Help and errors

- `-h` and `-?` print usage and exit. They must be used by themselves.
- Missing option arguments, unknown parameters, invalid `-v` syntax, or missing scripts cause argument parsing to fail.
- Jawk reports runtime problems through exceptions and exits with a non-zero status when execution fails.

## [Execution Notes](#execution-notes)

- `--dump-syntax`, `--dump-intermediate`, `-K`, `-h`, `-?`, and `--list-ext` are non-executing modes.
- `--profile` is an executing mode. It keeps normal AWK output on stdout and writes the profiling report to stderr after execution finishes.
- `--profile=<filename>` keeps normal AWK output on stdout and writes only the profiling report to the file.
- `-S` affects compilation and execution, not just runtime behavior.
- `--posix` currently disables arrays-of-arrays syntax and related subarray-only operands in order to keep CLI compilation aligned with classic POSIX-style AWK expectations.
- `--posix` is rejected together with `-L`, because loading precompiled tuples bypasses source compilation entirely.
- `-L` lets you skip source compilation, but the loaded tuples must still be compatible with the current runtime.
- `-f` and `-L` are distinct paths: source files compile now, tuple files load now.
- `--persist` and `JAWK_PERSISTENT_MEMORY` affect only real execution. Non-executing modes such as `-K`, `--dump-syntax`, and `--dump-intermediate` ignore persistent memory.

## [Tuple Serialization Compatibility](#tuple-serialization-compatibility)

Jawk tuples are reusable, but they should be treated as internal artifacts tied to the Jawk version that produced them.

- `-K` writes tuples to a file
- `-L` reads those tuples back
- version mismatches can cause tuple loading to fail
- the safe fix is to recompile the tuples with the current Jawk version

Persistent memory files use the same Java serialization machinery. They are therefore version-sensitive as well and should be discarded when Jawk reports an incompatibility.

## [See Also](#see-also)

- [Quickstart examples](cli.html)[2]
- [Java API equivalent flows](java.html)[3]
- [Compatibility caveats](compatibility.html)[4]