import

beet import [-CWAPRqst] [-l LOGPATH] PATH...
beet import [options] -L QUERY

Add music to your library, attempting to get correct tags for it from MusicBrainz.

Point the command at some music: directories, single files, or compressed archives. The music will be copied to a configurable directory structure and added to a library database. The command is interactive and will try to get you to verify MusicBrainz tags that it thinks are suspect. See the autotagging guide for detail on how to use the interactive tag-correction flow.

Directories passed to the import command can contain either a single album or many, in which case the leaf directories will be considered albums (the latter case is true of typical Artist/Album organizations and many people’s “downloads” folders). The path can also be a single song or an archive. Beets supports zip and tar archives out of the box. To extract rar files, install the rarfile package and the unrar command. To extract 7z files, install the py7zr package.

Optional command flags:

beet import --set genre="Alternative Rock" --set mood="emotional"

list

beet list [-apf] QUERY

Queries the database for music.

Want to search for “Gronlandic Edit” by of Montreal? Try beet list gronlandic. Maybe you want to see everything released in 2009 with “vegetables” in the title? Try beet list year:2009 title:vegetables. You can also specify the sort order. (Read more in query.)

You can use the -a switch to search for albums instead of individual items. In this case, the queries you use are restricted to album-level fields: for example, you can search for year:1969 but query parts for item-level fields like title:foo will be ignored. Remember that artist is an item-level field; albumartist is the corresponding album field.

The -p option makes beets print out filenames of matched items, which might be useful for piping into other Unix commands (such as xargs). Similarly, the -f option lets you specify a specific format with which to print every album or track. This uses the same template syntax as beets’ path formats. For example, the command beet ls -af '$album: $albumtotal' beatles prints out the number of tracks on each Beatles album. In Unix shells, remember to enclose the template argument in single quotes to avoid environment variable expansion.

remove

beet remove [-adf] QUERY

Remove music from your library.

This command uses the same query syntax as the list command. By default, it just removes entries from the library database; it doesn’t touch the files on disk. To actually delete the files, use the -d flag. When the -a flag is given, the command operates on albums instead of individual tracks.

When you run the remove command, it prints a list of all affected items in the library and asks for your permission before removing them. You can then choose to abort (type n), confirm (y), or interactively choose some of the items (s). In the latter case, the command will prompt you for every matching item or album and invite you to type y to remove the item/album, n to keep it or q to exit and only remove the items/albums selected up to this point. This option lets you choose precisely which tracks/albums to remove without spending too much time to carefully craft a query. If you do not want to be prompted at all, use the -f option.

modify

beet modify [-MWay] [-f FORMAT] QUERY [FIELD=VALUE...] [FIELD!...]

Change the metadata for items or albums in the database.

Supply a query matching the things you want to change and a series of field=value pairs. For example, beet modify genius of love artist="Tom Tom Club" will change the artist for the track “Genius of Love.” To remove fields (which is only possible for flexible attributes), follow a field name with an exclamation point: field!.

The -a switch operates on albums instead of individual tracks. Without this flag, the command will only change track-level data, even if all the tracks belong to the same album. If you want to change an album-level field, such as year or albumartist, you’ll want to use the -a flag to avoid a confusing situation where the data for individual tracks conflicts with the data for the whole album.

Items will automatically be moved around when necessary if they’re in your library directory, but you can disable that with -M. Tags will be written to the files according to the settings you have for imports, but these can be overridden with -w (write tags, the default) and -W (don’t write tags).

When you run the modify command, it prints a list of all affected items in the library and asks for your permission before making any changes. You can then choose to abort the change (type n), confirm (y), or interactively choose some of the items (s). In the latter case, the command will prompt you for every matching item or album and invite you to type y to apply the changes, n to discard them or q to exit and apply the selected changes. This option lets you choose precisely which data to change without spending too much time to carefully craft a query. To skip the prompts entirely, use the -y option.

move

beet move [-capt] [-d DIR] QUERY

Move or copy items in your library.

This command, by default, acts as a library consolidator: items matching the query are renamed into your library directory structure. By specifying a destination directory with -d manually, you can move items matching a query anywhere in your filesystem. The -c option copies files instead of moving them. As with other commands, the -a option matches albums instead of items. The -e flag (for “export”) copies files without changing the database.

To perform a “dry run”, just use the -p (for “pretend”) flag. This will show you a list of files that would be moved but won’t actually change anything on disk. The -t option sets the timid mode which will ask again before really moving or copying the files.

update

beet update [-F] FIELD [-aM] QUERY

Update the library (and, by default, move files) to reflect out-of-band metadata changes and file deletions.

This will scan all the matched files and read their tags, populating the database with the new values. By default, files will be renamed according to their new metadata; disable this with -M. Beets will skip files if their modification times have not changed, so any out-of-band metadata changes must also update these for beet update to recognise that the files have been edited.

To perform a “dry run” of an update, just use the -p (for “pretend”) flag. This will show you all the proposed changes but won’t actually change anything on disk.

By default, all the changed metadata will be populated back to the database. If you only want certain fields to be written, specify them with the `-F` flags (which can be used multiple times). For the list of supported fields, please see `beet fields`.

When an updated track is part of an album, the album-level fields of all tracks from the album are also updated. (Specifically, the command copies album-level data from the first track on the album and applies it to the rest of the tracks.) This means that, if album-level fields aren’t identical within an album, some changes shown by the update command may be overridden by data from other tracks on the same album. This means that running the update command multiple times may show the same changes being applied.

write

beet write [-pf] [QUERY]

Write metadata from the database into files’ tags.

When you make changes to the metadata stored in beets’ library database (during import or with the modify command, for example), you often have the option of storing changes only in the database, leaving your files untouched. The write command lets you later change your mind and write the contents of the database into the files. By default, this writes the changes only if there is a difference between the database and the tags in the file.

You can think of this command as the opposite of update.

The -p option previews metadata changes without actually applying them.

The -f option forces a write to the file, even if the file tags match the database. This is useful for making sure that enabled plugins that run on write (e.g., the Scrub and Zero plugins) are run on the file.

stats

beet stats [-e] [QUERY]

Show some statistics on your entire library (if you don’t provide a query) or the matched items (if you do).

By default, the command calculates file sizes using their bitrate and duration. The -e (--exact) option reads the exact sizes of each file (but is slower). The exact mode also outputs the exact duration in seconds.

fields

beet fields

Show the item and album metadata fields available for use in query and pathformat. The listing includes any template fields provided by plugins and any flexible attributes you’ve manually assigned to your items and albums.

config

beet config [-pdc]
beet config -e

Show or edit the user configuration. This command does one of three things:

zsh

If you use zsh, take a look at the included completion script. The script should be placed in a directory that is part of your fpath, and not sourced in your .zshrc. Running echo $fpath will give you a list of valid directories.

Another approach is to use zsh’s bash completion compatibility. This snippet defines some bash-specific functions to make this work without errors:

autoload bashcompinit
bashcompinit
_get_comp_words_by_ref() { :; }
compopt() { :; }
_filedir() { :; }
eval "$(beet completion)"