Boodler: The boodle-mgr Reference Manual

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

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

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

boodle-mgr list

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

boodle-mgr

...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 prompts for any arguments you do not provide on the command line.

Type boodle-mgr help for a complete list of commands. Type boodle-mgr --help or boodle-mgr -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 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 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 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 is safe, boodler 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 would incorporate some kind of sandboxing, to safeguard against malicious packages. Unfortunately, the design of Python makes this difficult.)

reload

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

lasterror

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

quit

Leave the interactive prompt and shut down boodle-mgr.

Return to Boodler docs index