.\" Man page generated from reStructuredText.
.
.TH "BEET" "1" "September 17, 2014" "1.3" "beets"
.SH NAME
beet \- music tagger and library organizer
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.nf
\fBbeet\fP [\fIargs\fP\&...] \fIcommand\fP [\fIargs\fP\&...]
\fBbeet help\fP \fIcommand\fP
.fi
.sp
.SH COMMANDS
.SS import
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
beet import [\-CWAPRqst] [\-l LOGPATH] PATH...
beet import [options] \-L QUERY
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Add music to your library, attempting to get correct tags for it from
MusicBrainz.
.sp
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 \fBautotagging guide\fP
for detail on how to use the interactive tag\-correction flow.
.sp
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\(aqs "downloads" folders). The path can also be a single
song or an archive. Beets supports \fIzip\fP and \fItar\fP archives out of the
box. To extract \fIrar\fP files, install the \fI\%rarfile\fP package and the
\fIunrar\fP command.
.sp
Optional command flags:
.INDENT 0.0
.IP \(bu 2
By default, the command copies files your the library directory and
updates the ID3 tags on your music. If you\(aqd like to leave your music
files untouched, try the \fB\-C\fP (don\(aqt copy) and \fB\-W\fP (don\(aqt write tags)
options. You can also disable this behavior by default in the
configuration file (below).
.IP \(bu 2
Also, you can disable the autotagging behavior entirely using \fB\-A\fP
(don\(aqt autotag)\-\-\-then your music will be imported with its existing
metadata.
.IP \(bu 2
During a long tagging import, it can be useful to keep track of albums
that weren\(aqt tagged successfully\-\-\-either because they\(aqre not in the
MusicBrainz database or because something\(aqs wrong with the files. Use the
\fB\-l\fP 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.
.IP \(bu 2
Relatedly, the \fB\-q\fP (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\(aqs
ability to resume interrupted imports.
.IP \(bu 2
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 \fB\-p\fP or "no" using \fB\-P\fP\&. The resuming feature can be
disabled by default using a configuration option (see below).
.IP \(bu 2
If you want to import only the \fInew\fP stuff from a directory, use the
\fB\-i\fP
option to run an \fIincremental\fP 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\(aqll need to use an incremental import \fIevery
time\fP you run an import on the directory in question\-\-\-including the first
time, when no subdirectories will be skipped. So consider enabling the
\fBincremental\fP configuration option.
.IP \(bu 2
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 \fB\-t\fP (for \fItimid\fP) option.
.IP \(bu 2
The importer typically works in a whole\-album\-at\-a\-time mode. If you
instead want to import individual, non\-album tracks, use the \fIsingleton\fP
mode by supplying the \fB\-s\fP option.
.IP \(bu 2
If you have an album that\(aqs split across several directories under a common
top directory, use the \fB\-\-flat\fP 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.
.IP \(bu 2
Similarly, if you have one directory that contains multiple albums, use the
\fB\-\-group\-albums\fP option to split the files based on their metadata before
matching them as separate albums.
.UNINDENT
.SS list
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
beet list [\-apf] QUERY
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBQueries\fP the database for music.
.sp
Want to search for "Gronlandic Edit" by of Montreal? Try \fBbeet list
gronlandic\fP\&.  Maybe you want to see everything released in 2009 with
"vegetables" in the title? Try \fBbeet list year:2009 title:vegetables\fP\&. You
can also specify the sort order. (Read more in \fBquery\fP\&.)
.sp
You can use the \fB\-a\fP 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 \fByear:1969\fP but query parts for item\-level fields
like \fBtitle:foo\fP will be ignored. Remember that \fBartist\fP is an item\-level
field; \fBalbumartist\fP is the corresponding album field.
.sp
The \fB\-p\fP option makes beets print out filenames of matched items, which might
be useful for piping into other Unix commands (such as \fI\%xargs\fP). Similarly, the
\fB\-f\fP option lets you specify a specific format with which to print every album
or track. This uses the same template syntax as beets\(aq \fBpath formats\fP\&. For example, the command \fBbeet ls \-af \(aq$album: $tracktotal\(aq
beatles\fP 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.
.SS remove
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
beet remove [\-ad] QUERY
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Remove music from your library.
.sp
This command uses the same \fBquery\fP syntax as the \fBlist\fP command.
You\(aqll 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\(aqt
touch the files on disk. To actually delete the files, use \fBbeet remove \-d\fP\&.
.SS modify
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
beet modify [\-MWay] QUERY [FIELD=VALUE...] [FIELD!...]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Change the metadata for items or albums in the database.
.sp
Supply a \fBquery\fP matching the things you want to change and a
series of \fBfield=value\fP pairs. For example, \fBbeet modify genius of love
artist="Tom Tom Club"\fP 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: \fBfield!\fP\&.
.sp
The \fB\-a\fP switch operates on albums instead of
individual tracks. Items will automatically be moved around when necessary if
they\(aqre in your library directory, but you can disable that with \fB\-M\fP\&. Tags
will be written to the files according to the settings you have for imports,
but these can be overridden with \fB\-w\fP (write tags, the default) and \fB\-W\fP
(don\(aqt write tags).  Finally, this command politely asks for your permission
before making any changes, but you can skip that prompt with the \fB\-y\fP switch.
.SS move
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
beet move [\-ca] [\-d DIR] QUERY
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Move or copy items in your library.
.sp
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 \fB\-d\fP manually, you can move items matching a query
anywhere in your filesystem. The \fB\-c\fP option copies files instead of moving
them. As with other commands, the \fB\-a\fP option matches albums instead of items.
.SS update
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
beet update [\-aM] QUERY
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Update the library (and, optionally, move files) to reflect out\-of\-band metadata
changes and file deletions.
.sp
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 \fB\-M\fP\&.
.sp
To perform a "dry run" of an update, just use the \fB\-p\fP (for "pretend") flag.
This will show you all the proposed changes but won\(aqt actually change anything
on disk.
.sp
When an updated track is part of an album, the album\-level fields of \fIall\fP
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\(aqt identical
within an album, some changes shown by the \fBupdate\fP command may be
overridden by data from other tracks on the same album. This means that
running the \fBupdate\fP command multiple times may show the same changes being
applied.
.SS write
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
beet write [\-pf] [QUERY]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Write metadata from the database into files\(aq tags.
.sp
When you make changes to the metadata stored in beets\(aq library database
(during import or with the \fI\%modify\fP command, for example), you often
have the option of storing changes only in the database, leaving your files
untouched. The \fBwrite\fP 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.
.sp
You can think of this command as the opposite of \fI\%update\fP\&.
.sp
The \fB\-p\fP option previews metadata changes without actually applying them.
.sp
The \fB\-f\fP 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.
.SS stats
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
beet stats [\-e] [QUERY]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Show some statistics on your entire library (if you don\(aqt provide a
\fBquery\fP) or the matched items (if you do).
.sp
The \fB\-e\fP (\fB\-\-exact\fP) option makes the calculation of total file size more
accurate but slower.
.SS fields
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
beet fields
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Show the item and album metadata fields available for use in \fBquery\fP and
\fBpathformat\fP\&. Includes any template fields provided by plugins.
.SS config
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
beet config [\-pd]
beet config \-e
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Show or edit the user configuration. This command does one of three things:
.INDENT 0.0
.IP \(bu 2
With no options, print a YAML representation of the current user
configuration. With the \fB\-\-default\fP option, beets\(aq default options are
also included in the dump.
.IP \(bu 2
The \fB\-\-path\fP option instead shows the path to your configuration file.
This can be combined with the \fB\-\-default\fP flag to show where beets keeps
its internal defaults.
.IP \(bu 2
With the \fB\-\-edit\fP option, beets attempts to open your config file for
editing. It first tries the \fB$EDITOR\fP environment variable and then a
fallback option depending on your platform: \fBopen\fP on OS X, \fBxdg\-open\fP
on Unix, and direct invocation on Windows.
.UNINDENT
.SH GLOBAL FLAGS
.sp
Beets has a few "global" flags that affect all commands. These must appear
between the executable name (\fBbeet\fP) and the command\-\-\-for example, \fBbeet \-v
import ...\fP\&.
.INDENT 0.0
.IP \(bu 2
\fB\-l LIBPATH\fP: specify the library database file to use.
.IP \(bu 2
\fB\-d DIRECTORY\fP: specify the library root directory.
.IP \(bu 2
\fB\-v\fP: verbose mode; prints out a deluge of debugging information. Please use
this flag when reporting bugs.
.IP \(bu 2
\fB\-c FILE\fP: read a specified YAML \fBconfiguration file\fP\&.
.UNINDENT
.sp
Beets also uses the \fBBEETSDIR\fP environment variable to look for
configuration and data.
.SH SHELL COMPLETION
.sp
Beets includes support for shell command completion. The command \fBbeet
completion\fP prints out a \fI\%bash\fP 3.2 script; to enable completion put a line
like this into your \fB\&.bashrc\fP or similar file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
eval "$(beet completion)"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or, to avoid slowing down your shell startup time, you can pipe the \fBbeet
completion\fP output to a file and source that instead.
.sp
You will also need to source the \fI\%bash\-completion\fP script, which is probably
available via your package manager. On OS X, you can install it via Homebrew
with \fBbrew install bash\-completion\fP; Homebrew will give you instructions for
sourcing the script.
.sp
The completion script suggests names of subcommands and (after typing
\fB\-\fP) options of the given command. If you are using a command that
accepts a query, the script will also complete field names.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
beet list ar[TAB]
# artist:  artist_credit:  artist_sort:  artpath:
beet list artp[TAB]
beet list artpath\e:
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
(Don\(aqt worry about the slash in front of the colon: this is a escape
sequence for the shell and won\(aqt be seen by beets.)
.sp
Completion of plugin commands only works for those plugins
that were enabled when running \fBbeet completion\fP\&. If you add a plugin
later on you will want to re\-generate the script.
.sp
If you use zsh, take a look instead at the included \fI\%completion script\fP\&.
.SH SEE ALSO
.sp
\fBhttp://beets.readthedocs.org/\fP
.sp
\fIbeetsconfig(5)\fP
.SH AUTHOR
Adrian Sampson
.SH COPYRIGHT
2012, Adrian Sampson
.\" Generated by docutils manpage writer.
.