Command-line reference
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; for what each command does, see Commands and targets.
Synopsis #
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). 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. 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. 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 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 (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.
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 — the narrative walk-through of the grammar.
- Commands and targets — what each command selects and runs.
- Environments and keyrings — the layers behind the environment contract.