ZKG(1)

📦
version 6.0.4 · 6 versions
, in fedora 43, fedora 44, ubuntu noble

💖 NAME 💖

okay so zkg is the Zeek Package Manager — literally a command-line package manager for Zeek, and it's giving main character energy fr fr. 🦋

here's the vibe, the whole synopsis:

           {test,install,bundle,unbundle,remove,uninstall,purge,refresh,upgrade,load,unload,pin,unpin,list,search,info,config,autoconfig,env,create,template} ...

✨ Options ✨

  • --version — show the program's version number and dip 💅
  • --configfile — the path to the Zeek Package Manager config file. Precludes --user. also, see Config File. 👀
  • --user=False — store, like, all the state in your home directory. Precludes --configfile. pick a lane bestie, you can't have both.
  • --verbose=0, -v=0 — more program output for debugging 🐛 stack it up for even more output, e.g. -vvv.
  • --extra-source — add an extra source. simple as that. 🌈

🌸 Environment Variables 🌸

👑 COMMANDS 👑

🧪 test 🧪

runs the unit tests for the Zeek packages you point at. heads up bestie: in most cases the zeek and zeek-config programs need to be in your PATH before you run this. no PATH, no party. 😭

🎀 Positional arguments 🎀

  • package — the name(s) of the package(s) to operate on. and okay so a package can be named, like, several ways:
    • if the package is part of a package source, you can refer to it by the base name of the package (the last component of the git URL) or by its path within the package source.
    • if two packages in different package sources have conflicting paths, then the package source name may be prepended to the package path to resolve the ambiguity.
    • a full git URL may also be used to refer to a package that doesn't belong to a source.

e.g. for a package source called "zeek" that has a package named "foo" located in either "alice/zkg.index" or "alice/bro-pkg.index", the following names work: "foo", "alice/foo", "zeek/alice/foo". ✨

✨ Options ✨

  • --version — the version of the package to test. only one package may be specified at a time when using this flag. you can put a version tag, a branch name, or a commit hash here. if the package name refers to a local git repo with a working tree, then its currently active branch is used. the default for other cases is to use the latest version tag, or if a package has none, the default branch, like "main" or "master". 💅

🫶 install 🫶

installs packages from a configured package source, or straight from a git URL. and after installing, the package gets marked as being "loaded" (peep the load command for that). 🎀

🎀 Positional arguments 🎀

  • package — the name(s) of the package(s) to operate on. a package can be named in several ways, okay:
    • if the package is part of a package source, it may be referred to by the base name of the package (last component of git URL) or its path within the package source.
    • if two packages in different package sources have conflicting paths, then the package source name may be prepended to the package path to resolve the ambiguity.
    • a full git URL may also be used to refer to a package that doesn't belong to a source.

e.g. for a package source called "zeek" that has a package named "foo" located in either "alice/zkg.index" or "alice/bro-pkg.index", the following names work: "foo", "alice/foo", "zeek/alice/foo". 🌈

✨ Options ✨

  • --skiptests=False — skip running unit tests for packages before installation. 🏃‍♀️
  • --nodeps=False — skip all dependency resolution/checks. > ⚠️ ngl this one is dangerous: using this option risks putting your installed package collection into a broken or unusable state. 🙈
  • --nosuggestions=False — skip automatically installing suggested packages.
  • --version — the version of the package to install. only one package may be specified at a time when using this flag. a version tag, branch name, or commit hash may be specified here. if the package name refers to a local git repo with a working tree, then its currently active branch is used. the default for other cases is to use the latest version tag, or if a package has none, the default branch, like "main" or "master". 💅
  • --force=False — don't prompt for confirmation or user variables. just go.
  • --user-var — a user variable assignment. this avoids prompting for input and lets you provide a value when using --force. use it repeatedly as needed for multiple values. 🍓

🧹 remove 🧹

unloads (see the unload command) and uninstalls a previously installed package. bye bestie 👋

🎀 Positional arguments 🎀

  • package — the name(s) of the package(s) to operate on. the package may be named in several ways:
    • if the package is part of a package source, it may be referred to by the base name of the package (last component of git URL) or its path within the package source.
    • if two packages in different package sources have conflicting paths, then the package source name may be prepended to the package path to resolve the ambiguity.
    • a full git URL may also be used to refer to a package that does not belong to a source.

e.g. for a package source called "zeek" that has a package named "foo" located in either "alice/zkg.index" or "alice/bro-pkg.index", the following names work: "foo", "alice/foo", "zeek/alice/foo". ✨

✨ Options ✨

  • --force=False — skip the confirmation prompt. no take-backs.
  • --nodeps=False — skip all dependency resolution/checks. > ⚠️ yeah so using this option risks putting your installed package collection into a broken or unusable state. not me warning you twice. 💀
NOTE: you may also say uninstall. same thing, we don't gatekeep. 🫶

🔥 purge 🔥

unloads (see the unload command) and uninstalls all previously installed packages. everything. gone. it's giving clean slate. 😌

✨ Options ✨

  • --force=False — skip the confirmation prompt.

🎁 bundle 🎁

this command creates a bundle file containing a collection of Zeek packages. if --manifest is used, you supply the list of packages to put in the bundle; else, all currently installed packages get put in the bundle. a bundle file can be unpacked on any target system, resulting in a repeatable/specific set of packages being installed on that target system (see the unbundle command). 📦

this is lowkey iconic for anyone managing packages on a system that otherwise has limited network connectivity. e.g. one can use a system with an internet connection to create a bundle, transport that bundle to the target machine using whatever means are appropriate, and finally unbundle/install it on the target machine. 🌈✨

🎀 Positional arguments 🎀

  • filename.bundle — the path of the bundle file to create. it will be overwritten if it already exists. also note: if --manifest is used before this filename is specified, you should use a double-dash, --, to first terminate that argument list. iykyk 💅

✨ Options ✨

  • --force=False — skip the confirmation prompt.
  • --nodeps=False — skip all dependency resolution/checks. > ⚠️ using this option risks creating a bundle of packages that is in a broken or unusable state. bestie. please.
  • --nosuggestions=False — skip automatically bundling suggested packages.
  • --manifest — this may either be a file name or a list of packages to include in the bundle. if a file name is supplied, it should be in INI format with a single [bundle] section. the keys in that section correspond to package names and their values correspond to git version tags, branch names, or commit hashes. the values may be left blank to indicate that the latest available version should be used. 🎀

🦋 unbundle 🦋

this command unpacks a bundle file formerly created by the bundle command and installs all the packages contained within. surprise, it's a present 🎁

🎀 Positional arguments 🎀

  • filename.bundle — the path of the bundle file to install.

✨ Options ✨

  • --replace=False — using this flag first removes all installed packages before then installing the packages from the bundle. it's giving out with the old. 👑
  • --force=False — don't prompt for confirmation or user variables.
  • --user-var — a user variable assignment. this avoids prompting for input and lets you provide a value when using --force. use repeatedly as needed for multiple values. 🍓

🔄 refresh 🔄

retrieve the latest package metadata from sources, and check whether any installed packages have available upgrades. note that this does not actually upgrade any packages (see the upgrade command for that, bestie). it's a vibe check, not a glow-up. ✨

✨ Options ✨

(the refresh option list picks right back up in part 2 — hold that thought 💜)

  • --aggregate=False — okay so this one goes out and crawls every url listed in the package source's zkg.index file (or the legacy bro-pkg.index, we don't gatekeep) and hoovers up all the metadata it finds in the matching zkg.meta files (or legacy bro-pkg.meta — yes, both, always). Then it stashes that aggregated metadata in the local clone of the package source that zkg keeps around internally for locating package metadata. For each package, the metadata gets pulled from the highest available git version tag, or from the default branch like main or master if there are literally no version tags. ✨
  • --fail-on-aggregate-problems=False — only matters when you're also using --aggregate. Turn this on and zkg will exit with an error if any packages trigger metadata problems. Normally those problems are just a lil warning and nobody's stressed. 🙈
  • --push=False — pushes all your local changes to the package sources up to the upstream repos. 🚀
  • --sources — a list of package source names you wanna operate on. Skip this argument entirely and the command just operates on all configured sources. main character energy, no favorites. 👑

🦋 upgrade

Upgrades the package(s) you point at to the latest available version. Don't name any packages? Then it upgrades every installed package that's outdated and not pinned. 💅 And here's the tea: if a package was installed with --version using a git branch name, it gets updated to the latest commit on that branch. Otherwise it goes to the highest available git version tag.

usage: zkg upgrade [-h] [--skiptests] [--nodeps] [--nosuggestions] [--force] [--user-var NAME=VAL] [package ...]

📍 Positional arguments

  • package — the name(s) of package(s) you wanna operate on, and bestie there are several ways to name them. If the package lives in a package source, you can refer to it by the base name of the package (that's the last component of the git URL) or by its path within the package source. If two packages in different package sources have conflicting paths, you can prepend the package source name to the package path to clear up the ambiguity. You can also use a full git URL to refer to a package that doesn't belong to a source. E.g. for a package source called zeek that has a package named foo located in either alice/zkg.index or alice/bro-pkg.index, all of these names work: foo, alice/foo, zeek/alice/foo. 🫶

⚙️ Options

  • --skiptests=False — skips running unit tests for packages before installation. yolo mode, kind of. 😭
  • --nodeps=False — skips all dependency resolution/checks. > Heads up: using this option risks putting your installed package collection into a broken or unusable state. Do not do this casually, fr fr.
  • --nosuggestions=False — skips automatically installing suggested packages.
  • --force=False — don't prompt for confirmation or user variables. just goes for it.
  • --user-var — a user variable assignment. This avoids prompting for input and lets you provide a value when you're using --force. Use it repeatedly as needed for multiple values. 🔁

🌸 load

So the Zeek Package Manager keeps track of every package marked as "loaded", and it maintains a single Zeek script that — when Zeek loads it, e.g. via @load packages — will load the scripts from all "loaded" packages all at once. Iconic. This command adds a set of packages to the "loaded packages" list. ✨

usage: zkg load [-h] [--nodeps] package [package ...]

📍 Positional arguments

  • package — name(s) of package(s) to load.

⚙️ Options

  • --nodeps=False — skips all dependency resolution/checks. > Again, this risks putting your installed package collection into a broken or unusable state. 😬

🎀 unload

Same lore as before: the Zeek Package Manager tracks everything marked as "loaded" and maintains a single Zeek script that, when Zeek loads it, will load the scripts from all "loaded" packages at once. This command removes a set of packages from the "loaded packages" list. bye bestie 👋

usage: zkg unload [-h] [--force] [--nodeps] package [package ...]

📍 Positional arguments

  • package — the name(s) of package(s) to operate on. The package can be named in a bunch of ways. If it's part of a package source, refer to it by the base name of the package (last component of the git URL) or its path within the package source. If two packages in different package sources have conflicting paths, prepend the package source name to the package path to resolve the ambiguity. A full git URL also works for a package that doesn't belong to a source. E.g. for a package source called zeek that has a package named foo located in either alice/zkg.index or alice/bro-pkg.index, these names work: foo, alice/foo, zeek/alice/foo. 💖

⚙️ Options

  • --force=False — skips the confirmation prompt. no take-backsies screen.
  • --nodeps=False — skips all dependency resolution/checks. > And yeah, this risks putting your installed package collection into a broken or unusable state. 💀

🧚 pin

Pinned packages are simply ignored by the upgrade command. that's the whole vibe.

usage: zkg pin [-h] package [package ...]

📍 Positional arguments

  • package — the name(s) of package(s) to operate on. Naming works multiple ways: if it's part of a package source, use the base name of the package (last component of git URL) or its path within the package source. If two packages in different package sources have conflicting paths, prepend the package source name to the package path to clear it up. A full git URL also refers to a package that doesn't belong to a source. E.g. for a package source called zeek that has a package named foo located in either alice/zkg.index or alice/bro-pkg.index, these all work: foo, alice/foo, zeek/alice/foo. ⭐

🌈 unpin

Packages that are not pinned get automatically upgraded by the upgrade command. so this is the un-pausing of your faves.

usage: zkg unpin [-h] package [package ...]

📍 Positional arguments

  • package — the name(s) of package(s) to operate on. The package may be named several ways. If the package is part of a package source, you can refer to it by the base name of the package (last component of git URL) or its path within the package source. If two packages in different package sources have conflicting paths, then the package source name may be prepended to the package path to resolve the ambiguity. A full git URL may also be used to refer to a package that does not belong to a source. E.g. for a package source called zeek that has a package named foo located in either alice/zkg.index or alice/bro-pkg.index, the following names work: foo, alice/foo, zeek/alice/foo. 🦋

🔥 list

Outputs a list of packages that match a given category. menu, but make it packages.

usage: zkg list [-h] [--nodesc] [{all,installed,not_installed,loaded,unloaded,outdated}]

📍 Positional arguments

  • category — the package category used to filter the listing.

Possible choices: all, installed, not_installed, loaded, unloaded, outdated

⚙️ Options

  • --nodesc=False — don't display description text, just the package name(s). minimalism 💅

Performs a substring search on package names and metadata tags. And here's the trick: surround your search text with slashes to say it's a regular expression (e.g. /text/). 🧠✨

usage: zkg search [-h] search_text [search_text ...]

📍 Positional arguments

  • search_text — the text(s) or pattern(s) to look for.

👑 info

Shows detailed information/metadata for the packages you give it. If a package is currently installed, you get extra info about its status too — like the installed version, or whether it's currently marked as "pinned" or "loaded." the receipts, basically. 🎀

usage: zkg info [-h] [--version VERSION] [--nolocal] [--json] [--jsonpretty SPACES] [--allvers] package [package ...]

📍 Positional arguments

  • package — the name(s) of package(s) to operate on. The package may be named in several ways. If the package is part of a package source, it may be referred to by the base name of the package (last component of git URL) or its path within the package source. If two packages in different package sources have conflicting paths, then the package source name may be prepended to the package path to resolve the ambiguity. A full git URL may also be used to refer to a package that does not belong to a source. E.g. for a package source called zeek that has a package named foo located in either alice/zkg.index or alice/bro-pkg.index, the following names work: foo, alice/foo, zeek/alice/foo. And one more thing bestie: if a single name is given and it matches one of the same categories as the list command, then it's automatically expanded to be the names of all packages which match the given category. 🤯

⚙️ Options

  • --version — the version of the package metadata to inspect. A version tag, branch name, or commit hash — and only one package at a time may be given when using this flag. If unspecified, the behavior depends on whether the package is currently installed. If installed, the metadata gets pulled from the installed version. If not installed, the latest version tag is used, or if a package has no version tags, the default branch like main or master is used. 🙌
  • --nolocal=False — don't read information from locally installed packages. Instead read info from remote GitHub. 🌐
  • --json=False — output package information as JSON.
  • --jsonpretty — optional number of spaces to indent when you're pretty-printing JSON output. ✨
  • --allvers=False — when you're spitting out package info as JSON, this shows metadata for all the versions. Heads up bestie, this one can be slow because remote repositories may get cloned multiple times. Also: installed packages will only show metadata for the installed version unless you also pass --nolocal. 💀

config 💅

By default this command spits out a valid package manager config file that matches the one you're currently using — but with all the defaulted field values filled in. Cute, right? And if you pass it the name of a specific field as an argument, it'll output just that field's value instead. Obsessed. 🎀

usage: zkg config [-h] [{all,sources,user_vars,state_dir,script_dir,plugin_dir,bin_dir,zeek_dist,bro_dist}]

Positional arguments:

  • config_param — name of a specific config file field to output.

Possible choices: all, sources, user_vars, state_dir, script_dir, plugin_dir, bin_dir, zeek_dist, bro_dist

autoconfig 🌸

This one outputs a valid package manager config file that's generated using the zeek-config script that comes installed with Zeek. It's the suggested configuration for most Zeek installations, no cap. For this command to work, the zeek-config (or bro-config) script has to be in your PATH — unless you pass --user, in which case it creates a config that doesn't touch your Zeek installation at all. 🦋

usage: zkg autoconfig [-h] [--force]

Options:

  • --force=False — skips any confirmation prompt. just sends it. 🔥

env 🧚

This command returns shell commands that, when executed, will correctly set ZEEKPATH and ZEEK_PLUGIN_PATH (and also BROPATH and BRO_PLUGIN_PATH for legacy compatibility, iykyk) so you can use the scripts and plugins from packages the package manager installed. For it to function properly, either have the zeek-config script (installed by zeek) in your PATH, or have the ZEEKPATH and ZEEK_PLUGIN_PATH (or BROPATH and BRO_PLUGIN_PATH) environment variables already set so this command can append package-specific paths to them. 💖

usage: zkg env [-h]

create 👑

This command creates a brand new Zeek package in the directory you give it via --packagedir. If that directory already exists, zkg will not modify it unless you provide --force. respect the boundaries bestie 💅

usage: zkg create [-h] --packagedir DIR [--version VERSION] [--features FEATURE [FEATURE ...]] [--template URL] [--force] [--user-var NAME=VAL]

Options:

  • --packagedir — output directory into which to produce the new package. Required.
  • --version — the template version to use. You can specify a version tag, a branch name, or a commit hash here. If --template refers to a local git repo with a working tree, then zkg uses it as-is and the version is ignored. The default for other cases is to use the latest version tag, or — if a template has none — the default branch, like main or master. 🌈
  • --features — additional features to include in your package. Use the template info command for info about which features are available. ⭐
  • --template — by default zkg uses its own package template. This makes it select an alternative.
  • --force=False — don't prompt for confirmation or user variables. 😤
  • --user-var — a user variable assignment. This avoids prompting for input and lets you provide a value when using --force. Use it repeatedly as needed for multiple values. 🍓

template info 🎀

This command shows you versions and supported features for a given package. the way it just tells you things 🫶

usage: zkg template info [-h] [--json] [--jsonpretty SPACES] [--version VERSION] [URL]

Positional arguments:

  • URL — URL of a package template repository, or a local path to one. When not provided, the configured default template is used.

Options:

  • --json=False — output template information as JSON.
  • --jsonpretty — optional number of spaces to indent for pretty-printed JSON output. ✨
  • --version — the template version to report on. A version tag, branch name, or commit hash may be specified here. If the selected template refers to a local git repo, the version is ignored. The default for other cases is to use the latest version tag, or if a template has none, the default branch, like main or master.

CONFIG FILE 🦋

The zkg command-line tool uses an INI-format config file so users can customize their Package Sources, Package installation paths, Zeek executable/source paths, and other zkg options. it's giving customizable 💅

See the default/example config file below for explanations of the available options and how to customize them:

# This is an example config file for zkg to explain what
# settings are possible as well as their default values.
# The order of precedence for how zkg finds/reads config files:
#
# (1) zkg --configfile=/path/to/custom/config
# (2) the ZKG_CONFIG_FILE environment variable
# (3) a config file located at $HOME/.zkg/config
# (4) if none of the above exist, then zkg uses builtin/default
#     values for all settings shown below

[sources]

# The default package source repository from which zkg fetches
# packages.  The default source may be removed, changed, or
# additional sources may be added as long as they use a unique key
# and a value that is a valid git URL.  The git URL may also use a
# suffix like "@branch-name" where "branch-name" is the name of a real
# branch to checkout (as opposed to the default branch, which is typically
# "main" or "master"). You can override the package source zkg puts
# in new config files (e.g. "zkg autoconfig")  by setting the
# ZKG_DEFAULT_SOURCE environment variable.
zeek = https://github.com/zeek/packages

[paths]

# Directory where source repositories are cloned, packages are
# installed, and other package manager state information is
# maintained.  If left blank or with --user this defaults to
# $HOME/.zkg. In Zeek-bundled installations, it defaults to
# <zeek_install_prefix>/var/lib/zkg/.
state_dir =

# The directory where package scripts are copied upon installation.
# A subdirectory named "packages" is always created within the
# specified path and the package manager will copy the directory
# specified by the "script_dir" option of each package's zkg.meta
# (or legacy bro-pkg.meta) file there.
# If left blank or with --user this defaults to <state_dir>/script_dir.
# In Zeek-bundled installations, it defaults to
# <zeek_install_prefix>/share/zeek/site.
# If you decide to change this location after having already
# installed packages, zkg will automatically relocate them
# the next time you run any zkg command.
script_dir =

# The directory where package plugins are copied upon installation.
# A subdirectory named "packages" is always created within the
# specified path and the package manager will copy the directory
# specified by the "plugin_dir" option of each package's zkg.meta
# (or legacy bro-pkg.meta) file there.
# If left blank or with --user this defaults to <state_dir>/plugin_dir.
# In Zeek-bundled installations, it defaults to
# <zeek_install_prefix>/lib/zeek/plugins.
# If you decide to change this location after having already
# installed packages, zkg will automatically relocate them
# the next time you run any zkg command.
plugin_dir =

# The directory where executables from packages are linked into upon
# installation.  If left blank or with --user this defaults to <state_dir>/bin.
# In Zeek-bundled installations, it defaults to <zeek_install_prefix>/bin.
# If you decide to change this location after having already
# installed packages, zkg will automatically relocate them
# the next time you run any zkg command.
bin_dir =

# The directory containing Zeek distribution source code.  This is only
# needed when installing packages that contain Zeek plugins that are
# not pre-built.  The legacy name of this option is "bro_dist".
zeek_dist =

[templates]

# The URL of the package template repository that the "zkg create" command
# will instantiate by default.
default = https://github.com/zeek/package-template

[user_vars]

# For any key in this section that is matched for value interpolation
# in a package's zkg.meta (or legacy bro-pkg.meta) file, the corresponding
# value is substituted during execution of the package's `build_command`.
# This section is typically automatically populated with the
# the answers supplied during package installation prompts
# and, as a convenience feature, used to recall the last-used settings
# during subsequent operations (e.g. upgrades) on the same package.

AUTHOR 💜

The Zeek Project

2019, The Zeek Project

okay and that's the whole page bestie!! 🎉 this was zkg version 2.14.0, dated Jul 05, 2023, filed under ZKG(1) — go forth and package-manage the house down 💅✨🫶

📦 where this page comes from