bw-menu 0.1.0

Pop-up BitWarden desktop quick-search. Puts the selection into the clipboard. Persists the vault login for the duration of the login session.

bw-dmenu

Pop-up BitWarden desktop quick-search. Puts the selection into the clipboard. Persists the vault login for the duration of the user's session. Supports multiple accounts simultaneously.

Can be configured to type out rather than use the clipboard.

Installation

Requires:

• Python 3.9+
• BitWarden CLI
• dmenu/wofi (for X/Wayland respectively)
• xclip/wl-copy (for X/Wayland respectively)

You can install with [pip]:

python3 -m pip install bw-dmenu

Or install from source:

git clone <url>
pip install bw-dmenu

Usage

usage: bw-menu [-h] [--menu-format-string MENU_FORMAT_STRING]
               [--sync-interval SYNC_INTERVAL]
               [--print-by-id PRINT_BY_ID PRINT_BY_ID]
               [--prepend-folders | --no-prepend-folders | -p]
               [--prepend-account-label | --no-prepend-account-label | -l]
               [--output-format-string OUTPUT_FORMAT_STRING]
               [--include-session-key | --no-include-session-key | -k]
               [--clipboard-cmd CLIPBOARD_CMD] --account LABEL
               BITWARDENCLI_APPDATA_DIR VAULT_URI API_CLIENT_ID [--verbose]

        Pop-up BitWarden desktop quick-search. Puts the selection into the
        clipboard. Persists the vault login for the duration of user's session.
        Supports multiple accounts simultaneously.

            bw-menu --account account_label ~/path/to/appdata \
                https://vault.domain.tld <api_client_id>

        Configuring the pop-up menu:

            `bw-menu` tries to default to appropriate menu commands for
            your compositor - `dmenu` on X and `wofi` on Wayland.

            If you wish to override this, it is preferred to do so via
            evironment variables:

                # A custom prompt
                export MENU_CMD='dmenu -i -p "My custom prompt" -l 7'

                # Or even use a different menu program
                export MENU_CMD='rofi -dmenu -p "" -i'

                # Wayland
                export MENU_CMD='wofi -dmenu -p "" -i'

        Configuring the Clipboard:

            `bw-menu` tries to default to appropriate clipboard commands for
            your compositor - `xclip` on X and `wl-copy` on Wayland.

            If you wish to override this, it is preferred to do so via
            evironment variables:

                # Xclip
                export CLIPBOARD_CMD='xclip -selection clipboard -in -loops 1'

                # Xsel
                export CLIPBOARD_CMD='xsel --selectionTimeout 5000 --input --clipboard'

                # On wayland, wl-copy
                export CLIPBOARD_CMD='wl-copy --paste-once'
        Examples:

            Type output via `xdotool` instead of putting to clipboard

                CLIPBOARD_CMD='xdotool -' bw-menu --account account_label \
                    ~/path/to/appdata https://vault.domain.tld <api_client_key> \
                    --output-format-string 'type {passphrase}'

        Security:

            Note: The default clipboard commands limit persistence. Overriding
            the clipboard commands and failing to limit persistence could
            present a security risk. Be careful.



options:
  -h, --help            show this help message and exit
  --menu-format-string MENU_FORMAT_STRING, -f MENU_FORMAT_STRING
                        String for Python's `str.format()` which determines
                        how items are listed in dmenu. The fields made
                        available are: `name`, `account_label`, `itemid`, and
                        `secret`
  --sync-interval SYNC_INTERVAL, -i SYNC_INTERVAL
                        The BitWarden CLI does not automatically pull new
                        information after login. This option allows the user
                        to specify a maximum interval (inminutes) after which
                        this tool will sync the local vault after running.
                        Anegative value prevents this application from syncing
                        the vault.
  --print-by-id PRINT_BY_ID PRINT_BY_ID
                        If a specific item ID is given here, `bw-menu` will
                        not prompt for a selection or output to the clipboard,
                        instead printing the given id directly to STDOUT.
  --prepend-folders, --no-prepend-folders, -p
                        If set, will prepend folder names to the items listed.
                        Note: this will make the run take longer, as the
                        BitWarden CLI must be called twice. (default: False)
  --prepend-account-label, --no-prepend-account-label, -l
                        If set, will prepend the account label to the items
                        listed. Useful if using multiple accounts. (default:
                        False)
  --output-format-string OUTPUT_FORMAT_STRING, -o OUTPUT_FORMAT_STRING
                        String for Python's `str.format()` which allows
                        dressing up of theoutput to the clipboard. The only
                        fields available is `passphrase`.This can be used in
                        combination with the `CLIPBOARD_CMD`environment
                        variable to, for example, have this tool type
                        theselection out automatically. See `bw-menu --help`
                        for more.
  --include-session-key, --no-include-session-key, -k
                        If set, this tool will include the active session key
                        in the dmenu output (default: False)
  --clipboard-cmd CLIPBOARD_CMD, -c CLIPBOARD_CMD
  --account LABEL BITWARDENCLI_APPDATA_DIR VAULT_URI API_CLIENT_ID, -a LABEL BITWARDENCLI_APPDATA_DIR VAULT_URI API_CLIENT_ID
                        The details necessary to log in to a vault with API
                        key. `LABEL` is not used in any interaction with the
                        vault (that is what the API keys are for), but only to
                        differentiate between multiple accounts internally.
  --verbose, -v         Set output verbosity on STDERR (-v=warning, -vv=debug)

Overriding menu and clipbaord commands

The default menu commands are dmenu and wofi on X and Wayland respectively.

This program tries to select reasonable defaults depending on the detected compositor by inspecting the XDG_SESSION_TYPE environment variable.

The menu command can be overridden with any tool that takes input on STDIN and outputs a selection.

The clipboard commands can be overridden with any tool that takes input on STDIN.

For guidance on overriding the menu and clipboard commands further, see the help output above.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

To run the test suite:

# Dependent targets create venv and install dependencies
make

Please make sure to update tests along with any changes.

License

License :: OSI Approved :: MIT License