NEST(1)

NAME
nest - Parrot Security tool catalog and launcher

SYNOPSIS
nest [--help]
nest list [--all | --installed | --available] [--json]
nest search term [--json]
nest info tool [--json]
nest run tool [--local | --container] [--runtime podman|docker] [--image ref] [-- args...]
nest cleanup [--running] [--images] [--dry-run] [--yes] [--runtime podman|docker] [--json]
nest refresh [--runtime podman|docker] [--json]
nest version [--json]

DESCRIPTION
nest is the official CLI companion of Parrot Security Linux. It answers two questions: which security tools does Parrot provide (and which of them are installed on this system), and how to launch a tool — locally on the host, or inside a podman/docker container when it is not installed.

The tool catalog is a curated YAML file describing every tool the Parrot project ships. Catalog copies are resolved in the following order; the valid copy with the highest version field wins, and the user copy wins ties:

1.  The path given by --catalog path or by the NEST_CATALOG environment variable (development and testing).

2.  The user copy, ~/.local/share/nest/tools.yaml, written by nest refresh.

3.  The system copy, /usr/share/nest/tools.yaml, shipped by the nest package.

Results are written to standard output; diagnostics, warnings and progress go to standard error. Running nest with no command prints the help text and exits successfully.

COMMANDS

list [--all | --installed | --available]
    [--json] List cataloged tools. --all (the default outside containers) shows everything, --installed only tools detected on this system, and --available only tools that are not installed locally but have a container image available.

search term
    Case-insensitive substring match of term over tool names, descriptions, packages and tags, always over the full catalog. No matches is not an error.

info tool
    Show full details of one catalog entry: description, package, executables (marking which exist), container images and options, tags, install status, and the suggested run command. Exits with status 3 if the tool is not in the catalog.

run tool [options] [-- args...]
    Launch tool. Mode resolution: --local and --container override the default_mode configuration key; inside a container only local runs are possible. The command executed is always the tool's first cataloged executable; everything after -- is passed to it verbatim.

    In local mode the tool is not installed, the command fails with status 3 and prints either a hint to run it in a container or an apt install hint. In container mode the image is --image or the tool's default catalog image; it is pulled if missing. The host persistence directory is created first and bind-mounted at /persistence inside the container, which is started run --rm -i (with -t only on a terminal) and labeled io.parrot.nest.managed=true.

cleanup [--running] [--images] [--dry-run] [--yes]
    [--runtime podman|docker] [--json] Remove nest-managed container resources; only resources carrying the io.parrot.nest.managed=true label are touched. By default only stopped containers are removed. --running also stops and removes running containers and requires confirmation (an interactive prompt, or --yes). --images also removes catalog-referenced images present locally. --dry-run only prints what would be removed. Volumes are never pruned. Not available inside a container (exit status 4).

refresh [--runtime podman|docker]
    [--json] Fetch the latest catalog from the pinned HTTPS URL (overridable for testing, see ENVIRONMENT), validate it, and install it to the user data directory if its version is strictly newer. The system catalog (/usr/share/nest/tools.yaml) is never touched; it is updated by the nest package itself. Afterwards, each unique catalog image already present locally is pulled so the container runtime updates it; images that are not local are never pulled.

version [--json]
    Print the nest version, the catalog version and its source path, the detected container runtime, and whether nest is running inside a container.

OPTIONS
Most options are documented above with their commands. Options common to several commands:

--json
    Emit machine-readable JSON instead of plain tables. The schemas are stable contracts; empty collections are serialized as empty arrays.

[--runtime podman|docker]
    Force a container runtime instead of the default auto-detection, which prefers podman and falls back to docker. An unknown value is a usage error.

--help, -h
    Print help for nest or for a subcommand.

EXIT STATUS

0   Success.

1   Generic error (invalid catalog, unreadable configuration, fetch failure, ...).

2   Usage error (unknown command or flag, missing confirmation, ...).

3   Tool not found in the catalog, or not installed for a local run.

4   Container runtime unavailable, or the operation is not possible inside a container.

ENVIRONMENT

NEST_CATALOG
    Path to an alternative catalog file, replacing all standard locations.

NEST_CATALOG_URL
    Override the pinned HTTPS URL used by nest refresh (testing only).

NEST_PERSISTENCE_DIR
    Host directory bind-mounted into containers at /persistence. Default: ~/nest/persistence.

XDG_DATA_HOME
    Honored when locating the user catalog copy.

XDG_CONFIG_HOME
    Honored when locating the per-user configuration file.

FILES

/usr/share/nest/tools.yaml
    System tool catalog shipped by the nest package; read-only and updated with the package itself.

~/.local/share/nest/tools.yaml
    User catalog copy written by nest refresh.

/etc/nest/nest.yaml
    System-wide configuration file (optional).

~/.config/nest/nest.yaml
    Per-user configuration file (optional). Recognized keys: runtime, default_mode, persistence_dir, catalog_url.

~/nest/persistence
    Default host directory bind-mounted into containers.

NOTES
When nest runs inside a container, it lists only the tools available in that image, run works only locally, and cleanup is unavailable.

On macOS, nest works as a client of VM-backed runtimes (podman machine, Docker Desktop); the VM must already be running.

SEE ALSO
podman(1), docker(1), apt(8)

Full project documentation: https://codeberg.org/palinuro/nest

AUTHOR
Lorenzo "Palinuro" Faletra <palinuro@parrotsec.org>