`punix search`¶

Search packages in a PCL tree whose pname or description matches a regex.

punix search REGEX [FILE] [--scenario NAME]

What it does¶

Loads FILE (a .pcl file or a directory of them) and type-checks. If FILE is omitted, discovers it from $PUNIX_PACKAGES or ./packages/.
Iterates every package module (one with a recipe field).
For each, evaluates pname and meta.description.
Prints one line per match: <pname> <version> <description>.

The regex is case-insensitive and applied to pname OR description. No network, no build — just composes the tree and matches.

Default `FILE` discovery¶

FILE is optional. When omitted, Punix discovers the packages tree from (first match wins):

$PUNIX_PACKAGES — explicit operator intent. If set but the path doesn't exist, exit 2.
./packages/ — convention. Must exist as a directory in the current working directory.

Otherwise exit 2 with no packages tree found: pass --file PATH, set PUNIX_PACKAGES, or cd into a directory containing a 'packages/' subdir.

Example¶

$ cd ~/projects/my-pcl-tree    # has a packages/ subdir

$ punix search node
node-18         18.20.8  Open-source, cross-platform JavaScript runtime
node-bootstrap  22.12.0
node_exporter   1.8.2    Prometheus exporter for hardware and OS metrics

$ punix search history
atuin           18.3.0   magical shell history

$ punix search '^a'              # regex: pname starts with 'a'
atuin           18.3.0   magical shell history

$ punix search node /other/tree  # explicit FILE
…

No matches → exit 0 with no output (grep convention).

Output formats¶

TTY (default) — tabulate-rendered padded columns; the description column is truncated with … so each row fits the terminal width.
Pipe (auto-detected) — tab-separated, one line per package, no truncation. Greppable: punix search node | awk -F'\t' '{print $1}'.
--format json — machine-readable JSON array.
--format text / --format tsv — force a specific mode regardless of TTY.
--no-truncate — in TTY mode, keep descriptions full-width (may wrap).

Options¶

--file FILE — explicit PCL file or directory; overrides the default discovery.
--format text|tsv|json — output format (default auto: TTY → text, pipe → tsv).
--no-truncate — disable description truncation in TTY mode.
--scenario NAME — evaluate under scenario NAME (see Modules).

Errors¶

Symptom	Cause
`error: invalid regex 'X': …` (exit 2)	The regex doesn't compile. The Python `re` error message is included.
Type-check errors (`[E#]`)	The PCL tree doesn't type-check; surfaces as the same located error you'd get from `punix check`.

Performance¶

Composes the tree once per invocation, ~150 ms for ~100 packages. No on-disk index — the answer is always current with the source.

punix search¶