BEET(1)                              beets                             BEET(1)

NAME
       beet - music tagger and library organizer

SYNOPSIS
       beet [args...] command [args...]
       beet help command


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. To extract 7z files, install the py7zr package.

       Optional command flags:

       o By default, the command copies files to your library directory and
         updates the ID3 tags on your music. In order to move the files,
         instead of copying, use the -m (move) option. 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).

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

       o 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. You can later review the file manually or import skipped
         paths from the logfile automatically by using the --from-logfile
         LOGFILE argument.

       o 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
         performs a fallback action that can be configured using the
         quiet_fallback configuration or --quiet-fallback CLI option.  By
         default it pessimistically skip``s the file.  Alternatively, it can
         be used as is, by configuring ``asis.

       o 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).

       o 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.

       o If you don't want to record skipped files during an incremental
         import, use the --incremental-skip-later flag which corresponds to
         the incremental_skip_later configuration option.  Setting the flag
         prevents beets from persisting skip decisions during a
         non-interactive import so that a user can make a decision regarding
         previously skipped files during a subsequent interactive import run.
         To record skipped files during incremental import explicitly, use the
         --noincremental-skip-later option.

       o When beets applies metadata to your music, it will retain the value
         of any existing tags that weren't overwritten, and import them into
         the database. You may prefer to only use existing metadata for
         finding matches, and to erase it completely when new metadata is
         applied. You can enforce this behavior with the --from-scratch
         option, or the from_scratch configuration option.

       o 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.

       o 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.

       o 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.

       o 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.

       o 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.

       o 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.

       o You can supply --set field=value to assign field to value on import.
         Values support the same template syntax as beets' path formats.
         These assignments will merge with (and possibly override) the
         set_fields configuration dictionary. You can use the option multiple
         times on the command line, like so:

            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 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:
       $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 [-IMWay] [-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!.

       Values can also be templates, using the same syntax as path formats.
       For example, beet modify artist='$artist_sort' will copy the artist
       sort name into the artist field for all your tracks, and beet modify
       title='$track $title' will add track numbers to their title metadata.

       The -a option changes to querying album fields instead of track fields
       and also enables to operate on albums in addition to the 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.

       Modifications issued using -a by default cascade to individual tracks.
       To prevent this behavior, use -I/--noinherit.

       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 [-e] EXCLUDE_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). Alternatively,
       specify fields to not write with `-e` 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:

       o 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.

       o 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.

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

       o With the --edit option, beets attempts to open your config file for
         editing. It first tries the $EDITOR environment variable, followed by
         $EDITOR 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 ....

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

       o -d DIRECTORY: specify the library root directory.

       o -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.

       o -c FILE: read a specified YAML configuration file. This configuration
         works as an overlay: rather than replacing your normal configuration
         options entirely, the two are merged. Any individual options set in
         this config file will override the corresponding settings in your
         base configuration.

       o -p plugins: specify a comma-separated list of plugins to enable. If
         specified, the plugin list in your configuration is ignored. The long
         form of this argument also allows specifying no plugins, effectively
         disabling all plugins: --plugins=.

       o -P plugins: specify a comma-separated list of plugins to disable in a
         specific beets run. This will overwrite -p if used with it. To
         disable all plugins, use --plugins= instead.

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

SEE ALSO
       https://beets.readthedocs.org/

       beetsconfig(5)

AUTHOR
       Adrian Sampson

COPYRIGHT
       2016, Adrian Sampson

2.1                             January 2, 2025                        BEET(1)