bpkg Package Guidelines

Package details

Here we lay down some info on the structure of a package.


Every package must have a file called bpkg.json; it specifies package metadata on the JSON format. (For legacy reasons, this file may also be called package.json).

Here’s an example of a well-formed bpkg.json:

  "name": "term",
  "version": "0.0.1",
  "description": "Terminal utility functions",
  "scripts": [ "term.sh" ],
  "install": "make install"

All fields are mandatory except when noted. Here’s a detailed explanation on all fields:


The name attribute is required as it is used to tell bpkg where to put it in the deps/ directory in you project.

  "name": "my-script"

version (optional)

The version attribute is not required but can be useful. It should correspond to the version that is associated with the installed package.

  "version": "0.0.1"


A human readable description of what the package offers for functionality.

  "description": "This script makes monkeys jump out of your keyboard"


Indicates that the package is only intended to be installed as a script. This allows the omission of the -g or --global flag during installation.

  "global": "true"


Shell script used to invoke in the install script. This is required if the global attribute is set to true or if the -g or --global flags are provided.

  "install": "make install"


This is an array of scripts that will be installed into a project.

  "scripts": ["script.sh"]


This is an array of files that will be installed into a project.

  "files": ["bar.txt", "foo.txt"]

dependencies (optional)

This is a hash of dependencies. The keys are the package names, and the values are the version specifiers. If you want the latest code use 'master' in the version specifier. Otherwise, use a tagged release identifier. This works the same as bpkg install’s package/version specifiers.

  "dependencies": {
    "term": "0.0.1"

Packaging best practices

These are guidelines that we strongly encourage developers to follow.

Package exports

It’s nice to have a bash package that can be used in the terminal and also be invoked as a command line function. To achieve this the exporting of your functionality should follow this pattern:

if [[ ${BASH_SOURCE[0]} != $0 ]]; then
  export -f my_script
  my_script "${@}"
  exit $?

This allows a user to source your script or invoke as a script.

# Running as a script
$ ./my_script.sh some args --blah
# Sourcing the script
$ source my_script.sh
$ my_script some more args --blah