Provided by: bro-pkg_1.4.2-1_all bug

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

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