These docs are under active development.
Peios Learn
On this page
reference 9 min read

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, 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 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.
--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.
--allow-unanchored No-value Permit publish from source with unanchored provenance (otherwise unanchored_provenance).
--all No-value package/publish: act on every package definition instead of a selector.
--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 --env --keyring --refresh-source --allow-unanchored --all clean mode
build Yes Yes Yes Yes Yes Yes
test Yes Yes Yes Yes Yes Yes
install Yes Yes Yes Yes Yes Yes
package Yes Yes Yes Yes Yes Yes Yes
publish Yes Yes Yes Yes Yes Yes Yes Yes
clean 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"
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).
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