bro-pkg

usage: zkg [-h] [--version] [--configfile FILE | --user] [--verbose] [--extra-source NAME=URL]
           {test,install,bundle,unbundle,remove,uninstall,purge,refresh,upgrade,load,unload,pin,unpin,list,search,info,config,autoconfig,env,create,template}
           ...

--version

show program's version number and exit

--configfile

Path to Zeek Package Manager config file. Precludes --user. See Config File.

--user=False

Store all state in user's home directory. Precludes --configfile.

--verbose=0, -v=0

Increase program output for debugging. Use multiple times for more output (e.g. -vvv).

--extra-source

Add an extra source.

usage: zkg test [-h] [--version VERSION] package [package ...]

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

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

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

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

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

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

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

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

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

--force=False

Skip the confirmation prompt.

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

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.

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

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

filename.bundle

The path of the bundle file to install.

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

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

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

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

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

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

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

package

Name(s) of package(s) to load.

--nodeps=False

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

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

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

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

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

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

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

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

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

category

Package category used to filter listing. Possible choices: all, installed, not_installed, loaded, unloaded, outdated

--nodesc=False

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

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

search_text

The text(s) or pattern(s) to look for.

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

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.

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

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

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

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

--force=False

Skip any confirmation prompt.

usage: zkg env [-h]

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

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

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

URL

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

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

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