# CLI options

pperl accepts a small set of command-line flags. Most are `perl`-compatible;
a handful are pperl-specific (JIT, parallelism). The authoritative list is
whatever `pperl --help` prints; the tables below show those flags, extracted
from the interpreter source and rendered here on every documentation build.

:::{note}
The actual `pperl --help` output on the terminal is always in English -
the binary does not localise help strings. Translated documentation
shows the same flags with descriptions in the page's language so
readers can study what each flag does; flag tokens (`-T`,
`--threads=N`, …) are always verbatim.
:::

```{include} ../_generated/pperl-help-table.md
```

## Module search paths: `-I`, `PERL5LIB`, `@INC`

`-I dir` prepends `dir` to `@INC`, exactly like perl. Entries from
`-I` and from the `PERL5LIB` environment variable (`PERLLIB` as the
fallback; both ignored under taint mode) are additionally expanded:
if the directory has versioned children (`5.44.99`, `5.40.0`, ...),
those are added around the entry, nearest perl version first. This
makes `local::lib`- and Carton-style trees built by a real perl work
unmodified.

Two deliberate differences from perl:

- **No architecture subdirectories.** perl would also add
  `dir/5.44/x86_64-linux`-style children; pperl never does. It runs
  no compiled XS objects, so those directories hold nothing it could
  use, and skipping them avoids loading `.pm` wrappers that would die
  trying to bootstrap `.so` files.
- **Native modules win over every `@INC` entry.** Modules built into
  the pperl binary (see `PPERL_MODS` below) are served directly by
  `require`; a same-name `.pm` on disk is never loaded in front of
  them, no matter what `-I` says.

Two pperl-private search locations exist for parallel installations,
so a module can be provided to pperl WITHOUT touching the shared
perl trees:

- The `PPERL5LIB` environment variable: same syntax and expansion as
  `PERL5LIB`, honored immediately before it.
- The pperl overlay trees, probed before every host perl tree:
  `/usr/local/share/pperl/site_perl` (local overrides),
  `/usr/share/pperl/site_perl` and `/usr/share/pperl/vendor_perl`
  (packaged), each optionally with versioned children.

A `.pm` in either location outranks all host trees for pperl only -
the host perl never looks there. Neither can outrank a module built
into the binary.

The rest of `@INC` is built by probing the host's standard library
trees (Arch, Debian and Fedora layouts) rather than baking one
distribution's paths into the binary; `pperl -V` prints the real
result. Details and rationale:
[differences from upstream](guide/pperl-architecture/differences-from-upstream.md)
and the `@INC` reference in
[program input](p5/core/perlvar/args-env-inc.md).

## Environment variables

pperl sets several environment variables inside the process it runs, so
scripts can introspect the running interpreter:

| Variable           | Meaning                                                      |
|--------------------|--------------------------------------------------------------|
| `PPERL`            | Version string (same as `pperl -v`)                          |
| `PPERL_FEATURES`   | Comma-separated list of compiled-in Cargo features           |
| `PPERL_MODS`       | Comma-separated `Name/version` pairs for every native module |
| `PPERL_SHELL`      | Shell integration flavor (empty if `shell` feature off)      |
| `PPERL_STATIC`     | `yes` if the binary is musl-statically linked, else `no`     |

Run `pperl -V` to see all values for the current binary.