Pentect commands differ mainly in where plaintext is allowed to appear. Use this guide before reaching for the advanced resolve command.

Mask text or read a file

Task	Command	Plaintext destination
Mask UTF-8 stdin	pentect mask	Nowhere; protected text is printed
Read and mask a file	pentect read PATH	Nowhere; the file is not changed
Inspect a handle	pentect view HANDLE	Nowhere; only safe metadata is printed

read uses the filename to recognize formats and can retain safe recovery metadata in the active local store. Without an active store, read still masks the file but any emitted handles are intentionally one-run values and cannot be resolved later; Pentect prints a warning to stderr in that case. mask is always a one-run stdin filter.

macOS / Linux

cat .env | pentect mask
pentect read ./config.json
pentect view '<<API_TOKEN_0123456789abcdef>>'

PowerShell

Get-Content .env -Raw | pentect mask
pentect read .\config.json
pentect view '<<API_TOKEN_0123456789abcdef>>'

See Handles and Files and images for the protection details.

Run a local command

pentect exec requires a real command. It does not treat arbitrary text as a secret, filename, or handle lookup. Pentect restores known handles only at the local execution boundary, then masks stdout and stderr before displaying them.

Prefer the direct form after --; it avoids another quoting layer:

macOS / Linux

pentect exec -- git status --short
pentect exec 'printf "%s\n" "hello"'

PowerShell

pentect exec -- git status --short
pentect exec 'Write-Output "hello"'

The shell form is one command string. The direct form is a program name followed by separate arguments. A missing executable produces a fixed Pentect diagnostic; Pentect does not repeat the potentially sensitive command text.

For a program that reads one credential from stdin:

macOS / Linux

pentect exec --secret-stdin '<<SUDO_PASSWORD_0123456789abcdef>>' -- sudo -S -p '' command

PowerShell

pentect exec --secret-stdin '<<API_TOKEN_0123456789abcdef>>' -- .\consumer.exe

The restored value reaches the child process through stdin, but not the terminal, process arguments, injected environment bindings, or Pentect log. An ordinary or daemonized descendant therefore does not receive a Pentect binding from this mode. The receiving program can still deliberately copy, export, persist, or forward the bytes after reading them; the operating system cannot revoke such a copy. Pentect does not append a newline. Use --allow-secret-argv only when a target program cannot accept a safer channel; same-user processes may be able to inspect process arguments.

Resolve plaintext only when required

pentect resolve is advanced because its output is plaintext. With no path it reads stdin and prints plaintext. With paths it replaces known handles in each file in place.

pentect resolve config.masked.toml
cat masked.txt | pentect resolve > plaintext.txt

Both destination files now contain plaintext secret material. Prefer exec when a command can consume a handle without creating a plaintext file.

Diagnose and maintain the installation

Task	Command	Notes
View recent persistent diagnostics	pentect log --once --tail 100	Bounded output; values, bodies, headers, and URLs are not logged
Follow diagnostics	pentect log --follow	Reads retained history, then waits for live events
Locate the log file	pentect log --path	Prints the local path
Machine-readable diagnostics	pentect log --json --once --tail 100	Bounded JSONL suitable for support tooling
View local protection statistics	pentect metrics	Shows stable metric keys with readable names, occurrence counts, blocked restorations, bounded warning reasons, and plugin failures/timeouts; never shows values, handles, paths, URLs, plugin names, error text, or account identifiers
Machine-readable statistics	pentect metrics --json	Local JSON; no telemetry is sent
Check readiness	pentect doctor	Does not change configuration
Offer safe repairs	pentect doctor --fix	Confirms changes interactively
Check for an update	pentect update --check	Does not install
Update Pentect	pentect update	Uses the recorded package-manager scope when available
Remove Pentect	pentect uninstall	Keeps project data

For failures, include the value-free reason shown by pentect log --json --once --tail 100 and follow Troubleshooting. Installation-specific commands are documented in Install, and the complete option list is in the CLI reference.