# Command-line reference

_pekit / Reference_

> Every pekit flag with its value form, the command-by-flag capability matrix, validation rules, exit codes, and the full PEKIT_* environment contract.

This is the exhaustive reference for pekit's command line and the environment it
exports to the commands it runs. Every flag listed here is a real flag accepted
by the parser; there are no others. For a narrative walk-through of the grammar
and recipe location, see [Invocation and flags](/pekit/running/invocation.md);
for what each command does, see
[Commands and targets](/pekit/running/commands-and-targets.md).

## Synopsis

```text
pekit [global flags] <command> [args and flags]
pekit [global flags] workspace [workspace flags] <command> [args and flags]
```

`<command>` is exactly one of `build`, `test`, `install`, `package`, `publish`,
`clean`, `gen`, `verify`, `lock`, or `workspace`. Flags may appear before or after the command word and
are parsed identically on both sides — the sole exception is the `workspace` tail
(see [Workspace flags](#workspace-flags)). A bare `--` ends flag parsing; every
following token is captured verbatim as a positional selector. Positional
selectors may not begin with `-`.

There is **no `--help` and no `help` command**, and no version banner: `-V` is an
alias for the `--version` *selector*, not a print-version flag.

## Flag value forms

The shape of a flag determines how its value may be written.

| Shape | How a value is written |
|---|---|
| No-value | Never takes a value. `--flag=x` errors with `unexpected_flag_value`. |
| Required-value | `--flag value` **or** `--flag=value`. A missing next token, a next token that is `--` or begins with `-`, or an empty `--flag=` all error with `missing_flag_value`. |
| Optional-value | Value **only** via `--flag=value`. The bare `--flag` is valid and means an empty value; it never consumes the following token. |

## Global flags

Accepted by every command, before or after the command word. These are never
subject to the capability matrix below.

| Flag | Value form | Semantics |
|---|---|---|
| `--recipe <path\|dir>` | Required-value | Use this recipe instead of searching upward from the cwd. A directory means `<dir>/pekit.toml`. |
| `--workspace <path\|dir>` | Required-value | Use this workspace file/root. Valid **only** with the `workspace` command. |
| `--allow-unused` | No-value | Downgrade "command does not support this recognised flag" from a fatal error to a suppressed notice. |
| `--dry-run` | No-value | Run the full planning pipeline but stop before any side effect; emit plan events instead. |
| `--quiet` | No-value | Human renderer, routine progress suppressed (only `warning`, `artifact`, `publish`, `workspace_summary`, `lock`, `sign` events). |
| `--verbose` | No-value | Human renderer plus extra staging/progress events. |
| `--json` | No-value | Emit newline-delimited JSON events on stdout instead of the human log. |

The renderer is chosen from these flags: `--json` selects the JSON renderer
(with `--dry-run` it buffers and prints a single `plan` object); otherwise the
human renderer runs, in quiet mode when `--quiet` is set.

## Version, source, and build flags

These are command-specific: each is only accepted by the commands marked in the
[capability matrix](#capability-matrix). Passing one to a command that does not
support it is `unsupported_flag` unless `--allow-unused` is set.

| Flag | Value form | Meaning |
|---|---|---|
| `--version <v>`, `-V <v>` | Required-value | Select a single recipe version. `-V` is an exact alias. |
| `--latest` | No-value | Select only the newest available version. |
| `--all-versions` | No-value | Act on every available version. |
| `--local[=<path>]` | Optional-value | Use a local source tree instead of resolving source; bare form uses the default, `=<path>` overrides it. |
| `--prefer-local[=<path>]` | Optional-value | Use the local source when present, otherwise resolve normally. |
| `--no-build[=<list>]` | Optional-value | Reuse already-staged build targets. Bare form reuses all; `=a,b,c` reuses only the named build targets. Only affects `build`-kind targets whose stage already exists. |
| `--no-verify[=<list>]` | Optional-value | Skip the [gen drift-check pre-flight](/pekit/running/commands-and-targets.md#generating-source-gen-and-verify). Bare form skips all; `=a,b,c` skips only the named gen targets (an unknown name errors). On `package`/`publish` it passes through to the builds they trigger. |
| `--env <name>` | Required-value | Select the environment file layer. `main` (default) loads `env.pekit.toml`; `<name>` loads `<name>.env.pekit.toml`; `none` loads no env file. |
| `--keyring <name\|path>` | Required-value | Load a keyring file. A bare name resolves to `<name>.keyring.pekit.toml` searched in the workspace root then recipe root; a path-like value is used directly. Repeatable. |
| `--keyring.<path>=<value>` | Dotted, `=` required | Set a single keyring value inline. Requires a non-empty dotted path and the `=`; otherwise `invalid_keyring_flag`. Repeatable. |
| `--refresh-source` | No-value | Force source re-materialisation, ignoring any source cache. The [lockfile](/pekit/reference/supporting-files.md#pekitlock) is still enforced against the fresh download. |
| `--allow-unanchored` | No-value | Permit `publish` from source with unanchored provenance — no checksum **and** no lock entry (otherwise `unanchored_provenance`). |
| `--allow-unsigned` | No-value | Permit `publish` of peipkg-format packages without a configured [signing key](/pekit/reference/supporting-files.md#well-known-entries) (otherwise `unsigned_publish`). |
| `--repin` | No-value | `lock` only: re-download the selected version and **replace** its lock entry — the explicit accept-changed-upstream-bytes ceremony. Requires an exact single `--version`. |
| `--all` | No-value | `package`/`publish`: act on every package definition instead of a selector. `gen`/`verify`: act on every gen target. |
| `--output-only` | No-value | `clean`: remove managed output only, without running a clean target. |
| `--target-only` | No-value | `clean`: run the clean target only, without removing managed output. |

`--version`/`-V`, `--latest`, and `--all-versions` form one mutually-exclusive
group ("version selection"); `--local` and `--prefer-local` form the
"local source flags" group.

## Workspace flags

`workspace` delegates to another command. Its tail is parsed specially: the two
workspace-only flags must appear **after** `workspace` and **before** the
delegated command word. Everything after the delegated command is parsed as an
ordinary invocation of that command.

| Flag | Value form | Meaning |
|---|---|---|
| `--jobs <N>`, `--jobs=<N>` | Required-value, positive integer | Maximum concurrent members. Default `1`. A non-integer or value `<= 0` errors with `invalid_flag_value`. |
| `--fail-fast` | No-value | Abort the whole workspace run on the first member failure. |

Global flags (`--dry-run`, `--json`, `--recipe`, …) may also appear in the tail
before the delegated command. A **version/source/build** flag placed there is an
error (`missing_workspace_command`, *"workspace command flag … must appear after
the delegated command"*): those belong after the delegated command. The same
code fires when no delegated command follows at all. See
[Workspaces](/pekit/running/workspaces.md).

## Capability matrix

Which command accepts which flag group. Global flags and `workspace` flags are
omitted (global flags are accepted everywhere). A blank cell means the flag group
is unsupported for that command.

| Command | version selection | local source | `--no-build` | `--no-verify` | `--env` | `--keyring` | `--refresh-source` | `--allow-unanchored` | `--allow-unsigned` | `--all` | clean mode | `--repin` |
|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
| `build` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | | | | | |
| `test` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | | | | | |
| `install` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | | | | | |
| `package` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | | | Yes | | |
| `publish` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | | |
| `clean` | | | | | Yes | Yes | | | | | Yes | |
| `gen` | | | | | Yes | Yes | | | | Yes | | |
| `verify` | | | | | Yes | Yes | | | | Yes | | |
| `lock` | Yes | | | | | | Yes | | | | | Yes |

"clean mode" is the `--output-only` / `--target-only` pair.

## Validation and mutual-exclusion rules

The parser rejects contradictory or malformed invocations before doing any work.

| Rejected condition | Diagnostic |
|---|---|
| `--quiet` with `--verbose` | `--quiet and --verbose cannot be used together` |
| `--quiet` with `--json` | `--quiet and --json cannot be used together` |
| `--recipe` with `--workspace` | `--recipe and --workspace cannot be used together` |
| `--workspace` without the `workspace` command | `--workspace can only be used with the workspace command` |
| No command word | `missing_command` |
| More than one of `--version` / `--latest` / `--all-versions` | mutually exclusive |
| `--local` with `--prefer-local` | mutually exclusive |
| `--output-only` with `--target-only` | mutually exclusive |
| A recognised flag the effective command does not support | `unsupported_flag` (suppressed under `--allow-unused`) |
| `clean --output-only` with `--env` or `--keyring` | *"clean --output-only does not run a target, so … is unused"* (suppressed under `--allow-unused`) |
| `clean` with more than one selector | `invalid_selector` (clean accepts at most one) |
| `package`/`publish` with `--all` **and** a selector | *"--all cannot be combined with package selectors"* |
| `gen`/`verify` with `--all` **and** a selector | *"--all cannot be combined with gen/verify target selectors"* |
| `lock` with any selector | `invalid_selector` (lock does not accept selectors) |
| `lock --repin` without an exact single `--version` | `invalid_flags` (`--repin requires exactly one exact --version`) |
| `--no-verify` naming an unknown gen target | `missing_target` |
| A positional selector beginning with `-` | `invalid_selector` (use `--` before selector-like values) |

`--allow-unused` relaxes **only** the "recognised-but-unused" and
"clean `--output-only` unused env/keyring" checks; it never excuses unknown
flags, malformed values, the mutual-exclusion rules, or bad selectors.

## Exit codes

| Code | Meaning |
|---|---|
| `0` | Success. |
| `1` | Any error — bad invocation, missing recipe, failed target, and so on. |

There are no other exit codes.

## Environment contract

Before running a target's command, pekit constructs its environment in layers:
managed `PEKIT_*` variables, then keyring exports, then user-declared env
(workspace → source → recipe → env-file). The process inherits the parent
environment with these overlaid. User env **may not** define any `PEKIT_*`
variable — doing so is `reserved_env`. The command runs with its working
directory set to the source root (or the recipe root for a `clean` target).

### Always set

Exported for every target pekit runs.

| Variable | Value |
|---|---|
| `PEKIT_RECIPE_ROOT` | Directory containing the resolved recipe (`pekit.toml`). |
| `PEKIT_SOURCE_ROOT` | Root of the materialised source tree. Equals the recipe root for a non-delegated recipe. |
| `PEKIT_LITERAL_ROOT` | Root used to resolve `@source:` payload references. |
| `PEKIT_ROOT` | Per-source pekit work base (staging lives beneath it). |
| `PEKIT_OUT_BASE` | Base directory for this source's managed output. |
| `PEKIT_OUT` | This target's own stage directory (where it should write). |
| `PEKIT_COMMAND` | The command kind running the target (`build`, `test`, `install`, `clean`, `gen`, `verify`). |
| `PEKIT_TARGET` | The target's name. |
| `PEKIT_BUILD_TIMESTAMP` | Run start time, Unix seconds. |
| `PEKIT_SOURCE_TIMESTAMP` | Source provenance time, Unix seconds. |
| `PEKIT_WORKSPACE_ROOT` | Workspace root, or an **empty string** when not in a workspace (always set). |
| `PEKIT_DEPENDENCIES_FILE` | Path to the JSON dependency payload pekit writes for this target. |
| `PEKIT_DEPENDENCY_PROVIDER` | Selected env dependency provider (empty when none). |
| `PEKIT_DEPENDENCIES` | Resolved dependencies as `name constraint` lines, one per line (empty when none). |

### Set only when a version is selected

Exported only when the run resolves a non-empty version.

| Variable | Value |
|---|---|
| `PEKIT_VERSION` | Full version string. |
| `PEKIT_VERSION_MAJOR` | Major component. |
| `PEKIT_VERSION_MINOR` | Minor component. |
| `PEKIT_VERSION_PATCH` | Patch component. |
| `PEKIT_VERSION_PRERELEASE` | Pre-release component (may be empty). |
| `PEKIT_VERSION_BUILDMETA` | Build-metadata component (may be empty). |

### Per-dependency and per-keyring variables

| Variable pattern | When set | Value |
|---|---|---|
| `PEKIT_<NEED>_OUT` | One per entry in the target's `needs` | Stage directory of that needed build target. `<NEED>` is the target name upper-cased with `-` and `.` replaced by `_`. Two needs mapping to the same name is `env_collision`. |
| `PEKIT_KEYRING_<PATH>` | One per keyring leaf loaded via `--keyring` / `--keyring.<path>=<value>` | The keyring value. `<PATH>` is the dotted keyring path upper-cased, with each run of non-alphanumeric characters collapsed to a single `_` and trailing `_` trimmed. For example `--keyring.token=…` exports `PEKIT_KEYRING_TOKEN`, and a nested `[registry] token = …` exports `PEKIT_KEYRING_REGISTRY_TOKEN`. |

A keyring export that collides with a managed `PEKIT_*` variable or with a normal
env variable is `env_collision`.

## See also

- [Invocation and flags](/pekit/running/invocation.md) — the narrative walk-through of the grammar.
- [Commands and targets](/pekit/running/commands-and-targets.md) — what each command selects and runs.
- [Environments and keyrings](/pekit/recipes/environments-and-keyrings.md) — the layers behind the environment contract.

Related content:

- [Invocation and flags](/pekit/running/invocation.md)
- [Commands and targets](/pekit/running/commands-and-targets.md)
- [Recipe format reference](/pekit/reference/recipe-format.md)
- [Environments and keyrings](/pekit/recipes/environments-and-keyrings.md)
- [Dependencies and claims](/pekit/recipes/dependencies-and-claims.md)
- [Workspaces](/pekit/running/workspaces.md)