Boodler: The boodle-mgr.py Reference Manual

# Boodler: The `boodle-mgr.py` Reference Manual

The `boodle-mgr.py` script downloads, installs, and manages the Boodler packages in your collection. (To play soundscapes, see boodler.py.)

    boodle-mgr.py [ options ] [ command... ]

The script offers many commands. For example, to list all the packages you currently have installed:

    boodle-mgr.py list

You can also use the script interactively. If you just type:

    boodle-mgr.py

...then you will see a command prompt. Type "list" to list your packages. You can continue entering commands until you type "quit", "q", ".", or ctrl-C.

In general, `boodle-mgr.py` prompts for any arguments you do not provide on the command line.

Type `boodle-mgr.py help` for a complete list of commands. Type `boodle-mgr.py --help` or `boodle-mgr.py -h` for a complete list of options.

## Options

`--force`
  Skip "are you sure?" queries when deleting or overwriting package files. With this option, `boodle-mgr.py` will go ahead and do it without asking.
`--import`
  Permit the execution of Python code in Boodler packages. Only use this when you are packaging your own soundscapes for other people to use. (See the create command.)
`--data directory`
  Boodler stores all its data in this directory. By default, this is a hidden folder in your home directory. On a Mac, it will be in `~/Library/Application Support/Boodler`. On Linux or Windows, it will be a `~/.boodler` folder.
`--collection directory`
  Boodler stores downloaded packages in this directory. By default, this is the `Collection` subdirectory of the `--data` folder (given above). There is generally no reason to change this.
`--download directory`
  Boodler stores temporary files, such as not-yet-unzipped packages, in this directory. By default, this is the `Download` subdirectory of the `--data` folder (given above). There is generally no reason to change this.

## Environment variables

All of these environment variables are optional. You can set all of this information with command-line arguments. (And command-line arguments override environment variables, if provided.)

`$BOODLER_DATA`
  Boodler stores all its data in this directory. See the `--data` option.
`$BOODLER_COLLECTION`
  Boodler stores downloaded packages in this directory. See the `--collection` option.
`$BOODLER_DOWNLOAD`
  Boodler stores temporary files in this directory. See the `--download` option.

## Commands

#### `help`

List all available commands.

#### `help` command

Show some help on the given command.

#### `list`

List all the packages you have installed. If you have multiple versions of a package (which can happen), this ignores that, and just shows a single entry.

#### `listall`

List all of the packages you have installed, showing version numbers. If you have multiple versions of a package, this displays that fact.

#### `describe` package

#### `describe` package version

Describe a package. This displays all its metadata, which can include the title, author, license, and so on. It also shows what other package this package requires in order to work.

If you do not include the version number, this describes the most recent version of the package you have installed.

#### `describe` file

Describe a package stored in a ".boop" file.

#### `describe` url

Describe a package found at a URL. The package file is downloaded to a temporary location and inspected there.

(In interactive mode, `boodle-mgr.py` keeps temporary files cached until you quit. So if you do "describe url" followed by "install url", you won't download the file twice.)

#### `contents` package

#### `contents` package version

#### `contents` file

#### `contents` url

List the sounds and soundscapes contained in a package. (Soundscapes are labelled "agent", meaning a soundscape agent class.)

You can specify the name of an installed package, a ".boop" file on disk, or a URL to download and inspect.

#### `versions` package

List all the versions of package that are installed.

#### `obsolete`

Search through your collection, and list all the package versions which can safely be deleted. A package version is considered obsolete if you have a newer one installed, and no current package requires the older version.

After you install upgraded packages, you can use this command to see what can be deleted.

#### `requires` package

#### `requires` package version

Search through your collection, and list all the packages which require the one you named.

#### `install` url

Download a package from that URL, and install it in your collection.

#### `install` file

Install a package from a ".boop" file on disk.

#### `install` package version

Install a package from the Boodler web site.

(A future version of Boodler will be able to locate the newest version of a package on the web server, and install it. Until then, you have to supply an explicit version number.)

#### `delete` package

Delete a package from your collection. If you have multiple versions, delete all of them.

#### `delete` package version

Delete a particular version of a package from your collection.

#### `deleteall`

Delete every package in your collection.

#### `create` directory

#### `create` directory destfile

Create a Boodler package. If you do not specify a destination ".boop" file, Boodler will create one with an appropriate name ("package.version.boop", in the usual convention).

You must set up the source directory with valid metadata files, and the Python source or sound sample files that you want to include in your package. This requires a certain amount of care. See the Boodler manual for designing soundscapes.

Note: the "create" command will only work if you have specified `--import` on the command line. This awkward dance is intended to aid security. `boodle-mgr.py` will normally refuse to import Python code from packages. You should only use `--import` when you intend to use the "create" command, packaging up a soundscape that you created yourself.

(This security is somewhat chimerical right now. While `boodle-mgr.py` is safe, `boodler.py` can import any package you have installed. So a package containing a Trojan horse would not be dangerous to install, but it could do damage when you tried to play soundscapes from it. Ideally, a future version of `boodler.py` would incorporate some kind of sandboxing, to safeguard against malicious packages. Unfortunately, the design of Python makes this difficult.)

#### `reload`

Force `boodle-mgr.py` to re-scan your collection. You would only need to do this if some other process (or another copy of `boodle-mgr.py`) modified your collection directory while `boodle-mgr.py` was running.

#### `lasterror`

Display a full Python stack trace of the last error that occurred. This exists to aid debugging of `boodle-mgr.py`.

#### `quit`

Leave the interactive prompt and shut down `boodle-mgr.py`.

Return to Boodler docs index