Skip to content


Switch branches/tags
This branch is 82 commits ahead of stuartcryan:master.


Failed to load latest commit information.
Latest commit message
Commit time

Bitwarden Alfred Workflow

Access your Bitwarden passwords, secrets, attachments and more via this powerful Alfred Workflow

Table of contents


  • Completely rewritten in go
  • fast secret / item search thanks to caching (no secrets are cached only the keys/names)
    • cache is encrypted
  • access to (almost) all object information via this workflow
  • download attachments via this workflow
  • show favicons of the websites
  • auto update
  • auto Bitwarden sync in the background
  • auto lock on startup and after customizable idle time
  • uses the awgo framework/library
  • many customizations possible

Requires Alfred 4.1 or newer; NOT tested with Alfred 3

Bitwarden V2 - Alfred Workflow Demo


  • Download the latest release
  • Open the downloaded file in Finder
  • Make sure that the Bitwarden CLI version 1.19 or newer is installed
  • If running on macOS Catalina or later, you MUST add Alfred to the list of security exceptions for running unsigned software. See this guide for instructions on how to do this.
    • Yes, this sucks and is annoying, but there is unfortunately is no easy way around this. macOS requires a paying Developer account for proper app notarization. I'm afraid I'm not willing to pay a yearly subscription fee to Apple just so that this (free and open source) project doesn't pester macOS Gatekeeper.

PATH configuration

In many cases the bw and node executables are located in paths outside of the default system PATH.
Please configure the Alfred Worklow variables PATH accordingly.
In a normal terminal type which bw and copy the dirname (everything except the "bw") into the PATH workflow variable.
The best is to append it to the existing string and separate it by a colon (:)
Repeat the above steps for node, starting with which node.

Workflow PATH config


To use, activate Alfred and type .bw to trigger this workflow. From there:

  • type .bwauth for login/logout/unlock/lock
  • type .bwconfig for settings/sync/workflow update/help/issue reports
  • type any search term to search for secrets/notes/identities/cards
  • modifier keys and actions are presented in the subtitle, different actions are available depending on the object type

Login via APIKEY

Since version 2.4.1 the workflow supports login via the api key.
Get/create an api key via the web ui. See more information here
To use the api key login flow in the workflow set the workflow variable USE_APIKEY to true.
The workflow will then ask you for the client_id and client secret to login.
Immediately afterwards it will also ask to unlock with the master password to get a session key.
That is a separate step and required with the api key as login method.

Search- / Filtermode

Up to version < 2.1.0 the Fuzzy filtering a la Sublime Text was default. Starting with version 2.1.0 Alfreds internal filtering is default.

You can change the search-/filtermode yourself easily. This gif shows the 3 steps which need to be done for it: Change filter mode

Enable auto background sync

In version 2.3.0 the background sync mechanism was added.
It is using the macOS user LaunchAgent.

To install the sync configure the workflow variables:

  • AUTOSYNC_TIMES, this can be used to configure comma separated multiple sync times per day, e.g. 8:15,23:45
  • alternatively you can use AUTO_HOUR together with AUTO_MIN for only one sync time

Bitwarden needs to be unlocked for sync to work.

Install via Alfred keyword: .bwauto

Enable auto lock

In version 2.3.0 the background lock and lock on startup mechanism was added.
It is using the macOS user LaunchAgent.

To install the sync configure the workflow variables:

  • LOCK_TIMEOUT set to a time in minutes after which the workflow should be locked if it hasn't been used in the meantime

The LaunchAgent checks every 5 minutes if the lock timeout has been reached.

The LaunchAgent checks also on load (e.g. startup of the system and login of the user),
if the startup happened within the last 5 minutes, if so then it locks the Bitwarden workflow.

Install via Alfred keyword: .bwautolock

Advanced Features / Configuration

Name Comment Default Value
2FA_ENABLED enables or disables 2FA for login (can be set via .bwconfig ) true
2FA_NODE sets the mode for the 2FA (can be set via .bwconfig ), 0 app, 1, email (not tested), 2 duo (not tested), 3 yubikey (not tested), 4 U2F (not tested) 0
AUTO_HOUR sets the hour for the backround sync to run (is installed separately with .bwauto) 10
AUTO_MIN sets the minute for the backround sync to run (is installed separately with .bwauto) 0
AUTOSYNC_TIMES sets multiple times when bitwarden should sync with the server, this is used first and instead of AUTO_MIN and AUTO_HOUR 8:15,23:45
AUTO_FETCH_ICON_CACHE_AGE This defines how often the Workflow should check for an icon if is missing, it doesn't need to do it on every run hence this cache 1440 (1 day)
BW_EXEC defines the binary/executable for the Bitwarden CLI command bw
BW_DATA_PATH sets the path to the Bitwarden Cli data.json "~/Library/Application Support/Bitwarden CLI/data.json""
bw_keyword defines the keyword which opens the Bitwarden Alfred Workflow .bw
bwf_keyword defines the keyword which opens the folder search of the Bitwarden Alfred Workflow .bwf
bwauth_keyword defines the keyword which opens the Bitwarden authentications of the Alfred Workflow .bwauth
bwauto_keyword defines the keyword which opens the Bitwarden background sync agent .bwauto
bwautolock_keyword defines the keyword which opens the Bitwarden background lock agent .bwautolock
bwconf_keyword defines the keyword which opens the Bitwarden configuration/settings of the Alfred Workflow .bwconfig
DEBUG If enabled print additional debug information, specially about for the decryption process false
EMAIL the email which to use for the login via the Bitwarden CLI, will be read from the data.json of the Bitwarden CLI if present ""
EMPTY_DETAIL_RESULTS Show all information in the detail view, also if the content is empty false
ICON_CACHE_ENABLED Download icons for login items if a URL is set true
ICON_CACHE_AGE This defines how old the icon cache can get in minutes, if expired the Workflow will download icons again. If icons are missing the workflow will also try to download them unrelated to this timeout 43200 (1 month)
LOCK_TIMEOUT Besides the lock on startup this additional timeout is set to define when Bitwarden should be locked in case of no usage. 1440 (1 day)
MAX_RESULTS The number of items to display maximal in the search view 1000
MODIFIER_1 The first modifier key combination, possible options, which can be combined by comma separation, are "cmd,alt/opt,ctrl,shift,fn" alt
MODIFIER_2 The first modifier key combination, possible options, which can be combined by comma separation, are "cmd,alt/opt,ctrl,shift,fn" shift
MODIFIER_3 The first modifier key combination, possible options, which can be combined by comma separation, are "cmd,alt/opt,ctrl,shift,fn" ctrl
MODIFIER_4 The first modifier key combination, possible options, which can be combined by comma separation, are "cmd,alt/opt,ctrl,shift,fn" cmd,opt
MODIFIER_1_ACTION Action executed by the first modifier username,code
MODIFIER_2_ACTION Action executed by the second modifier url
MODIFIER_3_ACTION Action executed by the third modifier totp
MODIFIER_4_ACTION Action executed by the fourth modifier more
NO_MODIFIER_ACTION Action executed without modifier pressed password,card
OPEN_LOGIN_URL If set to false the url of an item will be copied to the clipboard, otherwise it will be opened in the default browser. true
OUTPUT_FOLDER The folder to which attachments should be saved when the action is triggered. Default is $HOME/Downloads. "~" can be used as well. ""
PATH The PATH env variable which is used to search for executables (like the Bitwarden CLI configured with BW_EXEC, security to get and set keychain objects) /usr/bin:/usr/local/bin:/usr/local/sbin:/usr/local/share/npm/bin:/usr/bin:/usr/sbin
REORDERING_DISABLED If set to false the items which are often selected appear further up in the results. true
SERVER_URL Set the server url if you host your own Bitwarden instance - you can also set separate domains for api,webvault etc e.g. --api http://localhost:4000 --identity http://localhost:33656
SKIP_TYPES Comma separated list of types which should not be listed in the Workflow. Clear the Workflow cache and sync again (in .bwconf ) Available types to skip: (login, note, card, identity) ""
SYNC_CACHE_AGE This defines how old the sync cache can get, if expired the Workflow will trigger a new sync with Bitwarden (values lower than 30 will be ignored and set to 30) 10080 (0 means disabled; unit is minutes)
TITLE_WITH_USER If enabled the name of the login user item or the last 4 numbers of the card number will be appended (added) at the end of the name of the item true
TITLE_WITH_URLS If enabled all the URLs for an login item will be appended (added) at the end of the name of the item true
USE_APIKEY If enabled an API KEY can be used to login, this is helpful to prevent problems with captches which Bitwarden cloud introduced recently false

Modifier Actions Explained

type action name
login password
note - (always copy the secret note)
cards card
identity - (always copy the name )
others more (to show all item entries, can't be NO_MODIFIER_ACTION)

You can place per type one action name into the ACTION config, a combination is possible where it is not overlapping with more or another of the same type.

Good examples:

MODIFIER_3_ACTION=password,card (2 items listed but of different type)

Bad examples:

MODIFIER_3_ACTION=code,card (2 items listed but of the same type, therefore this is not permitted and will cause problems)

Develop locally

  1. Install alfred cli
    go get -u

  2. Clone this repo.

  3. Link the workflow directory with Alfred
    cd workflow; alfred link

  4. Install dependency and run the first build
    make build

Colors and Icons

Light blue

Hex: #175DDC
RGB: 23,93,220

Darker blue

Hex: #134db7
RGB: 20,81,192

Get icons as pngs here and this is the browser

Licensing and Thanks

The icons are based on Bitwarden Brand , Font Awesome and Material Design Icons.

Parts of the README are taken over from alfred-aws-console-services-workflow


A big thanks to all code contributors but also to everyone who creates issues and helps that this workflow matures.

  • @luckman212
  • @blacs30

Though this repository was a fork, it has 0 code reference anymore to the forked repo because of watchers and stars I decided to leave it this way and not to "unlink" it - by creating a new clean repository

Source that helped me to get started


  • "I'm seeing the following dialog when running the workflow"



    Per the installation steps, you MUST add Alfred to the list of Developer Tool exceptions for Alfred to run any workflow that contains an executable (like this one)

  • Using bw cli and this workflow in parallel can possibly cause this error occurs Unexpected error. Exit code -1.

    The reason for that is when the bw cli is used in the terminal and the password is entered that a new session is initiated and the workflow's session invalidated.


    You can use the bash functions created by @luckman212 and located here in github
    Download the bash file and source it in your own .bash_profile or .zshrc

  • Getting a secret still takes very much time

    With version 2.2.0 this workflow decrypts the secrets without using the bw cli. This is much faster but it might possibly can fail.
    If it fails it falls back and uses the bw cli to get the secret. The decryption takes then more time again, was in the previous versions.


    To use the workflows faster decryption you can follow this instruction by Bitwarden)
    to update the encryption keys to the new mechanism.

    The linked doc doesn't specify how to force creation of a new key. It's easy though:

    • Login to your vault.
    • Click Settings at the top of the page.
    • Under My Account, scroll down to Encryption Key Settings.
    • Follow the instructions provided.
    • Logout (and on again) from Bitwarden on all devices.


Simple Bitwarden Workflow for Alfred







No packages published


  • Go 84.4%
  • Shell 8.3%
  • AppleScript 5.5%
  • Makefile 1.1%
  • Starlark 0.7%