Provided by: bro-pkg_1.3.3-1_all 
NAME
bro-pkg - Bro Package Manager
A command-line package manager for Bro.
usage: bro-pkg [-h] [--version] [--configfile CONFIGFILE] [--verbose]
{test,install,bundle,unbundle,remove,purge,refresh,upgrade,load,unload,pin,unpin,list,search,info,config,autoconfig,env}
...
Options:
--version
show program's version number and exit
--configfile
Path to Bro Package Manager config file.
See Config File.
--verbose=0, -v=0
Increase program output for debugging. Use multiple times for more output
(e.g. -vvv).
Environment Variables:
BRO_PKG_CONFIG_FILE: Same as --configfile option, but has less precedence.
COMMANDS
test
Runs the unit tests for the specified Bro packages. In most cases, the "bro" and
"bro-config" programs will need to be in PATH before running this command.
usage: bro-pkg 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 "bro" that has a package named "foo" located in
"alice/bro-pkg.index" the following names work: "foo", "alice/foo",
"bro/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 or branch name 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 "master" branch.
install
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: bro-pkg install [-h] [--force] [--skiptests] [--nodeps]
[--nosuggestions] [--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 "bro" that has a package named "foo" located in
"alice/bro-pkg.index" the following names work: "foo", "alice/foo",
"bro/alice/foo".
Options:
--force=False
Skip the confirmation prompt.
--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 or branch name 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 "master" branch.
remove
Unloads (see the unload command) and uninstalls a previously installed package.
usage: bro-pkg remove [-h] [--force] 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 "bro" that has a package named "foo" located in
"alice/bro-pkg.index" the following names work: "foo", "alice/foo",
"bro/alice/foo".
Options:
--force=False
Skip the confirmation prompt.
purge
Unloads (see the unload command) and uninstalls all previously installed packages.
usage: bro-pkg purge [-h] [--force]
Options:
--force=False
Skip the confirmation prompt.
bundle
This command creates a bundle file containing a collection of Bro packages. If --manifest
is used, the user suplies 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: bro-pkg bundle [-h] [--force] [--nodeps] [--nosuggestions]
[--manifest MANIFEST [MANIFEST ...]]
bundle_filename
Positional arguments:
bundle_filename
The path of the bundle file to create. It will be overwritten if it already
exists.
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 or branch names. 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.
usage: bro-pkg unbundle [-h] [--force] [--replace] bundle_filename
Positional arguments:
bundle_filename
The path of the bundle file to install.
Options:
--force=False
Skip the confirmation prompt.
--replace=False
Using this flag first removes all installed packages before then installing
the packages from the bundle.
refresh
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: bro-pkg refresh [-h] [--aggregate] [--push]
[--sources SOURCES [SOURCES ...]]
Options:
--aggregate=False
Crawls the urls listed in package source bro-pkg.index files and aggregates
the metadata found in their bro-pkg.meta files. The aggregated metadata is
stored in the local clone of the package source that bro-pkg uses internally
locating package metadata. For each package, the metadata is taken from the
highest available git version tag or the master branch if no version tags
exist
--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.
upgrade
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: bro-pkg upgrade [-h] [--force] [--skiptests] [--nodeps]
[--nosuggestions]
[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 "bro" that has a package named "foo" located in
"alice/bro-pkg.index" the following names work: "foo", "alice/foo",
"bro/alice/foo".
Options:
--force=False
Skip the confirmation prompt.
--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.
load
The Bro Package Manager keeps track of all packages that are marked as "loaded" and
maintains a single Bro script that, when loaded by Bro (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: bro-pkg load [-h] package [package ...]
Positional arguments:
package
Name(s) of package(s) to load.
unload
The Bro Package Manager keeps track of all packages that are marked as "loaded" and
maintains a single Bro script that, when loaded by Bro, will load the scripts from all
"loaded" packages at once. This command removes a set of packages from the "loaded
packages" list.
usage: bro-pkg unload [-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 "bro" that has a package named "foo" located in
"alice/bro-pkg.index" the following names work: "foo", "alice/foo",
"bro/alice/foo".
pin
Pinned packages are ignored by the upgrade command.
usage: bro-pkg 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 "bro" that has a package named "foo" located in
"alice/bro-pkg.index" the following names work: "foo", "alice/foo",
"bro/alice/foo".
unpin
Packages that are not pinned are automatically upgraded by the upgrade command
usage: bro-pkg 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 "bro" that has a package named "foo" located in
"alice/bro-pkg.index" the following names work: "foo", "alice/foo",
"bro/alice/foo".
list
Outputs a list of packages that match a given category.
usage: bro-pkg 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).
search
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: bro-pkg 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 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: bro-pkg 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 "bro" that has a package named "foo" located in
"alice/bro-pkg.index" the following names work: "foo", "alice/foo",
"bro/alice/foo".
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 "master" branch 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.
config
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: bro-pkg config [-h]
[{all,sources,user_vars,state_dir,script_dir,plugin_dir,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, bro_dist
autoconfig
The output of this command is a valid package manager config file that is generated by
using the bro-config script that is installed along with Bro. It is the suggested
configuration to use for most Bro installations. For this command to work, the bro-config
script must be in PATH.
usage: bro-pkg autoconfig [-h]
env
This command returns shell commands that, when executed, will correctly set BROPATH and
BRO_PLUGIN_PATH to utilize the scripts and plugins from packages installed by the package
manager. For this command to function properly, either have the bro-config script
(installed by bro) in PATH, or have the BROPATH and BRO_PLUGIN_PATH environment variables
already set so this command can append package-specific paths to them.
usage: bro-pkg env [-h]
CONFIG FILE
The bro-pkg command-line tool uses an INI-format config file to allow users to customize
their Package Sources, Package installation paths, Bro executable/source paths, and other
bro-pkg options.
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 bro-pkg to explain what
# settings are possible as well as their default values.
# The order of precedence for how bro-pkg finds/reads config files:
#
# (1) bro-pkg --configfile=/path/to/custom/config
# (2) the BRO_PKG_CONFIG_FILE environment variable
# (3) a config file located at $HOME/.bro-pkg/config
# (4) if none of the above exist, then bro-pkg uses builtin/default
# values for all settings shown below
[sources]
# The default package source repository from which bro-pkg 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.
bro = https://github.com/bro/packages
[paths]
# Directory where source repositories are cloned, packages are
# installed, and other package manager state information is
# maintained. If left blank, this defaults to $HOME/.bro-pkg
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 bro-pkg.meta
# file there.
# If left blank, this defaults to <state_dir>/script_dir
# A typical path to set here is <bro_install_prefix>/share/bro/site
# If you decide to change this location after having already
# installed packages, bro-pkg will automatically relocate them
# the next time you run any bro-pkg 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 bro-pkg.meta
# file there.
# If left blank, this defaults to <state_dir>/plugin_dir
# A typical path to set here is <bro_install_prefix>/lib/bro/plugins
# If you decide to change this location after having already
# installed packages, bro-pkg will automatically relocate them
# the next time you run any bro-pkg command.
plugin_dir =
# The directory containing Bro distribution source code. This is only
# needed when installing packages that contain Bro plugins that are
# not pre-built.
bro_dist =
[user_vars]
# For any key in this section that is matched for value interpolation
# in a package's 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 Bro Project
COPYRIGHT
2016, The Bro Project