zkg - Man Page

Runs the unit tests for the specified Zeek packages. In most cases, the "zeek" and "zeek-config" programs will need to be in PATH before running this command.

usage: zkg test [-h] [--version VERSION] 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".

Options:

--version

The version of the package to test.  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".

Installs packages from a configured package source or directly from a git URL.  After installing, the package is marked as being "loaded" (see the load command).

usage: zkg install [-h] [--skiptests] [--nodeps] [--nosuggestions] [--version VERSION] [--force] [--user-var NAME=VAL] 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".

Options:

--skiptests=False

Skip running unit tests for packages before installation.

--nodeps=False

Skip all dependency resolution/checks.  Note that 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.

--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.

Unloads (see the unload command) and uninstalls a previously installed package.

usage: zkg remove [-h] [--force] [--nodeps] 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".

Options:

--force=False

Skip the confirmation prompt.

--nodeps=False

Skip all dependency resolution/checks.  Note that using this option risks putting your installed package collection into a broken or unusable state.

NOTE:

You may also say uninstall.

Unloads (see the unload command) and uninstalls all previously installed packages.

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

Options:

--force=False

Skip the confirmation prompt.

This command creates a bundle file containing a collection of Zeek packages.  If --manifest is used, the user supplies the list of packages to put in the bundle, else all currently installed packages are 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 command may be useful for those that want to manage 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.

usage: zkg bundle [-h] [--force] [--nodeps] [--nosuggestions] [--manifest MANIFEST [MANIFEST ...] --] filename.bundle

Positional arguments:

filename.bundle

The path of the bundle file to create.  It will be overwritten if it already exists.  Note that if --manifest is used before this filename is specified, you should use a double-dash, --, to first terminate that argument list.

Options:

--force=False

Skip the confirmation prompt.

--nodeps=False

Skip all dependency resolution/checks.  Note that using this option risks creating a bundle of packages that is in a broken or unusable state.

--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.

This command unpacks a bundle file formerly created by the bundle command and installs all the packages contained within.

usage: zkg unbundle [-h] [--replace] [--force] [--user-var NAME=VAL] filename.bundle

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.

--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.

Retrieve latest package metadata from sources and checks whether any installed packages have available upgrades. Note that this does not actually upgrade any packages (see the upgrade command for that).

usage: zkg refresh [-h] [--aggregate] [--fail-on-aggregate-problems] [--push] [--sources SOURCES [SOURCES ...]]

Options:

--aggregate=False

Crawls the urls listed in package source zkg.index (or legacy bro-pkg.index) files and aggregates the metadata found in their zkg.meta (or legacy bro-pkg.meta) files.  The aggregated metadata is stored in the local clone of the package source that zkg uses internally for locating package metadata. For each package, the metadata is taken from the highest available git version tag or the default branch, like "main" or "master", if no version tags exist

--fail-on-aggregate-problems=False

When using --aggregate, exit with error when any packages trigger metadata problems. Normally such problems only cause a warning.

--push=False

Push all local changes to package sources to upstream repos

--sources

A list of package source names to operate on.  If this argument is not used, then the command will operate on all configured sources.

Uprades the specified package(s) to latest available version.  If no specific packages are specified, then all installed packages that are outdated and not pinned are upgraded.  For packages that are installed with --version using a git branch name, the package is updated to the latest commit on that branch, else the package is updated 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) 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:

--skiptests=False

Skip running unit tests for packages before installation.

--nodeps=False

Skip all dependency resolution/checks.  Note that using this option risks putting your installed package collection into a broken or unusable state.

--nosuggestions=False

Skip automatically installing suggested packages.

--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.

The Zeek Package Manager keeps track of all packages that are marked as "loaded" and maintains a single Zeek script that, when loaded by Zeek (e.g. via @load packages), will load the scripts from all "loaded" packages at once. 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

Skip all dependency resolution/checks.  Note that using this option risks putting your installed package collection into a broken or unusable state.

The Zeek Package Manager keeps track of all packages that are marked as "loaded" and maintains a single Zeek script that, when loaded by Zeek, will load the scripts from all "loaded" packages at once.  This command removes a set of packages from the "loaded packages" list.

usage: zkg unload [-h] [--force] [--nodeps] 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".

Options:

--force=False

Skip the confirmation prompt.

--nodeps=False

Skip all dependency resolution/checks.  Note that using this option risks putting your installed package collection into a broken or unusable state.

Pinned packages are ignored by the upgrade command.

usage: zkg pin [-h] 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".

Packages that are not pinned are automatically upgraded by the upgrade command

usage: zkg unpin [-h] 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".

Outputs a list of packages that match a given category.

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

Positional arguments:

category

Package category used to filter listing.

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

Options:

--nodesc=False

Do not display description text, just the package name(s).

Perform a substring search on package names and metadata tags.  Surround search text with slashes to indicate it is 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.

Shows detailed information/metadata for given packages. If the package is currently installed, additional information about the status of it is displayed.  E.g. the installed version or whether it is currently marked as "pinned" or "loaded."

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". If a single name is given and matches one of the same categories as the "list" command, then it is 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 will be 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

Do not 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 for pretty-printed JSON output.

--allvers=False

When outputting package information as JSON, show metadata for all versions. This option can be slow since remote repositories may be cloned multiple times. Also, installed packages will show metadata only for the installed version unless the --nolocal  option is given.

The default output of this command is a valid package manager config file that corresponds to the one currently being used, but also with any defaulted field values filled in.  This command also allows for only the value of a specific field to be output if the name of that field is given as an argument to the command.

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

The output of this command is a valid package manager config file that is generated by using the zeek-config script that is installed along with Zeek.  It is the suggested configuration to use for most Zeek installations.  For this command to work, the zeek-config (or bro-config) script must be in PATH, unless the --user option is given, in which case this creates a config that does not touch the Zeek installation.

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

Options:

--force=False

Skip any confirmation prompt.

This command returns shell commands that, when executed, will correctly set ZEEKPATH and ZEEK_PLUGIN_PATH (also BROPATH and BRO_PLUGIN_PATH for legacy compatibility) to use scripts and plugins from packages installed by the package manager. For this command to function properly, either have the zeek-config script (installed by zeek) in 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]

This command creates a new Zeek package in the directory provided via --packagedir. If this directory exists, zkg will not modify it unless you provide --force.

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.  A version tag, branch name, or commit hash may be specified 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 information about available features.

--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 repeatedly as needed for multiple values.

This command shows versions and supported features for a given package.

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

Positional arguments:

URL

URL of a package template repository, or 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".