Simple command line bookmark and/or tagging utility.

cli, bookmark, tag, utility
pip install bm==1.6.1



Simple command line bookmark and/or tagging utility.

In order to help using it to tag files and directories as well as urls, it recognises if the URL given is that of an existing file. If so, the absolute path is substituted to help scripting by piping the output and to escape ambiguity. This behaviour can be stopped by using the "--no-path-subs" option.

One way to see this program is to consider it a simple hashmap utility for bash that associates a set of strings (the tags) to another one (the url). Feel free to find other ways to use this program!

Msgpack is used as is it highly portable, language agnostic and yet highly efficient.

This script is written using python3.



Simple command line browser independant bookmark utility.

Usage: bm [options] [-r] URL TAG...
       bm [options]  -d  URL
       bm [options]  -l  [TAG]...
       bm [options]  -L  TAG...
       bm [options]  URL
       bm [options]  -i  SOURCE...
       bm [options]  -t

    URL     The url to bookmark
            If alone, print the tags associated with URL
            If the url corresponds to an existing file,
            the absolute path is substituted to URL
            If URL is '-', then the program looks for a list of URL
            comming from the standard input.
    TAG     The tags to use with the url.
    SOURCE  When uniting, the paths to the source files.

    -h, --help          Print this help and exit
    -r, --remove        Remove TAG from URL
    -d, --delete        Delete an url from the database
    -l, --list-every    List the urls with every of TAG
                        If no tag is given, list all urls
    -L, --list-any      List the urls with any of TAG
    -f, --file FILE     Use FILE as the database, can be an url
                        Default is ~/.bookmarks
    -t, --tags          List every tag present in the database
                        with how many times it is used.
                        Output is sorted from the least to the most used
    -i, --import        Import bookmarks from sources into the database.
    -c, --clean         Clean database on loading, removing duplicates
    -n, --no-path-subs  Disable file path substitution
    -v, --verbose       Displays the list of tags of each url when listing
    -w, --web           Open the results in a web browser
    --version           Print current version number


$ bm "" bad search engine

$ bm "" bad search engine

$ bm "" python official

$ bm -l search engine

$ bm -r "" bad

$ bm "" cool

$ bm ""

$ bm -l search engine

$ bm -l bad search engine

$ bm -L bad search engine

$ bm -l

$ bm -t

$ cat urls | bm - atag


The simplest method is to use:

pip install bm

Otherwise, you can do when in this directory

python3 setup install

This should install the dependancies as well.

An AUR package is available for archlinux as well:

yaourt -S bm

And you, how do you use it?

As many cli tools, bm is designed the Unix way: with composability in mind. This is why its output is mainly plain text, one entry per line with simple separators.

I use urxvt and the urxvt-perls that allow fast link openning from the terminal.

My main browser is qutebrowser but I had bm linked with dwb or firefox before. To do that I keep in my configuration two keybindings that execute external commands:

set-cmd-text -s :spawn -- bm '{url}'
set-cmd-text -s :spawn -- bm -w -v -l

That way, when on a page, I press b to bookmark the current url and just type the tags on the browser prompt. B is for searching, note how it uses the html display with -w to open the results in a new tab.

For synchronisation I relay on a script that scp's the bookmark file between my computers and then does a local file import.

As I work on some very big projects, I also use bm to bookmark paths and files so that I can quickly find an given set of files. To do that I have an alias in order not to mix this work and other urls.

alias fbm="bm -f ~/.path_bm"

As bm automatically expands relative paths it is well suited to this usage.

These are only some personal examples, I hope you'll find yours!

On the --clean option

There was a slight bug on version <1.6.0 that if you were creating a new entry with twice the same tag it wouldn't detect the doublon and store the tag twice.

I decided not to risk breaking existing databases, so I added the --clean option that cleans a bugged database removing double tags. Also, the bug is fixed, so you shouldn't have to run it more than once.


docopt or "pip install docopt"

msgpack or "pip install msgpack-python"

requests or "pip install requests"


This program is under the GPLv3 License.

You should have received a copy of the GNU General Public License along with this program. If not, see <>.


Main developper: Cédric Picard
Twitter:         @Cym13
GPG:             383A 76B9 D68D 2BD6 9D2B  4716 E3B9 F4FE 5CED 42CB