
Command-Line Interface
**********************


Commands
========


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.

Optional command flags:

* By default, the command copies files your the library directory and
  updates the ID3 tags on your music. If you'd like to leave your
  music files untouched, try the "-C" (don't copy) and "-W" (don't
  write tags) options. You can also disable this behavior by default
  in the configuration file (below).

* Also, you can disable the autotagging behavior entirely using "-A"
  (don't autotag)---then your music will be imported with its existing
  metadata.

* During a long tagging import, it can be useful to keep track of
  albums that weren't tagged successfully---either because they're not
  in the MusicBrainz database or because something's wrong with the
  files. Use the "-l" option to specify a filename to log every time
  you skip an album or import it "as-is" or an album gets skipped as a
  duplicate.

* Relatedly, the "-q" (quiet) option can help with large imports by
  autotagging without ever bothering to ask for user input. Whenever
  the normal autotagger mode would ask for confirmation, the quiet
  mode pessimistically skips the album. The quiet mode also disables
  the tagger's ability to resume interrupted imports.

* Speaking of resuming interrupted imports, the tagger will prompt you
  if it seems like the last import of the directory was interrupted
  (by you or by a crash). If you want to skip this prompt, you can say
  "yes" automatically by providing "-p" or "no" using "-P". The
  resuming feature can be disabled by default using a configuration
  option (see below).

* If you want to import only the *new* stuff from a directory, use the
  "-i" option to run an *incremental* import. With this flag, beets
  will keep track of every directory it ever imports and avoid
  importing them again. This is useful if you have an "incoming"
  directory that you periodically add things to. To get this to work
  correctly, you'll need to use an incremental import *every time* you
  run an import on the directory in question---including the first
  time, when no subdirectories will be skipped. So consider enabling
  the "incremental" configuration option.

* By default, beets will proceed without asking if it finds a very
  close metadata match. To disable this and have the importer ask you
  every time, use the "-t" (for *timid*) option.

* The importer typically works in a whole-album-at-a-time mode. If you
  instead want to import individual, non-album tracks, use the
  *singleton* mode by supplying the "-s" option.

* If you have an album that's split across several directories under a
  common top directory, use the "--flat" option. This takes all the
  music files under the directory (recursively) and treats them as a
  single large album instead of as one album per directory. This can
  help with your more stubborn multi-disc albums.

* Similarly, if you have one directory that contains multiple albums,
  use the "--group-albums" option to split the files based on their
  metadata before matching them as separate albums.

* If you want to preview which files would be imported, use the "--
  pretend" option. If set, beets will just print a list of files that
  it would otherwise import.

* If you already have a metadata backend ID that matches the items to
  be imported, you can instruct beets to restrict the search to that
  ID instead of searching for other candidates by using the "--search-
  id SEARCH_ID" option. Multiple IDs can be specified by simply
  repeating the option several times.


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 *Queries*.)

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: $tracktotal' 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.
You'll be shown a list of the files that will be removed and asked to
confirm. By default, this just removes entries from the library
database; it doesn't touch the files on disk. To actually delete the
files, use "beet remove -d". If you do not want to be prompted to
remove the files, use "beet remove -f".


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. 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* or *n*. 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.

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, optionally, 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 *Queries*
and *Path Formats*. 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:

* With no options, print a YAML representation of the current user
  configuration. With the "--default" option, beets' default options
  are also included in the dump.

* The "--path" option instead shows the path to your configuration
  file. This can be combined with the "--default" flag to show where
  beets keeps its internal defaults.

* By default, sensitive information like passwords is removed when
  dumping the configuration. The "--clear" option includes this
  sensitive data.

* With the "--edit" option, beets attempts to open your config file
  for editing. It first tries the "$EDITOR" environment variable and
  then a fallback option depending on your platform: "open" on OS X,
  "xdg-open" on Unix, and direct invocation on Windows.


Global Flags
============

Beets has a few "global" flags that affect all commands. These must
appear between the executable name ("beet") and the command---for
example, "beet -v import ...".

* "-l LIBPATH": specify the library database file to use.

* "-d DIRECTORY": specify the library root directory.

* "-v": verbose mode; prints out a deluge of debugging information.
  Please use this flag when reporting bugs. You can use it twice, as
  in "-vv", to make beets even more verbose.

* "-c FILE": read a specified YAML *configuration file*.

Beets also uses the "BEETSDIR" environment variable to look for
configuration and data.


Shell Completion
================

Beets includes support for shell command completion. The command "beet
completion" prints out a bash 3.2 script; to enable completion put a
line like this into your ".bashrc" or similar file:

   eval "$(beet completion)"

Or, to avoid slowing down your shell startup time, you can pipe the
"beet completion" output to a file and source that instead.

You will also need to source the bash-completion script, which is
probably available via your package manager. On OS X, you can install
it via Homebrew with "brew install bash-completion"; Homebrew will
give you instructions for sourcing the script.

The completion script suggests names of subcommands and (after typing
"-") options of the given command. If you are using a command that
accepts a query, the script will also complete field names.

   beet list ar[TAB]
   # artist:  artist_credit:  artist_sort:  artpath:
   beet list artp[TAB]
   beet list artpath\:

(Don't worry about the slash in front of the colon: this is a escape
sequence for the shell and won't be seen by beets.)

Completion of plugin commands only works for those plugins that were
enabled when running "beet completion". If you add a plugin later on
you will want to re-generate the script.


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