Dorothy is a dotfile ecosystem featuring:
- seamless support for bash, fish, and zsh
- seamless support for multiple operating systems and architectures
- seamless support for your favorite terminal and GUI editors
- automatic configuration of your environment variables for what you have installed on your system
- automatic installation and updating of your specified packages
- automatic git ssh and gpg configuration based on what your system supports and your configuration
- hundreds of commands to improve your productivity
- completely extensible and configurable with your own user repository
- all this together, allows you to go from zero to hero within minutes, instead of days, on a brand new machine
Dorothy maintainers are daily driving Dorothy on:
- macOS on Apple Silicon
- macOS on Intel
- Ubuntu Server on Raspberry Pi 4 (ARM)
- Ubuntu Desktop on Raspberry Pi 400 (ARM)
- Ubuntu Desktop on Intel/AMD (x86_64)
Dorothy users are daily driving Dorothy on:
- Manjaro/Arch on Intel/AMD (x86_64)
Dorothy maintainers and users are occasionally driving Dorothy on:
- macOS on Apple Silicon with
- Fedora via Intel/AMD (x84_64) virtual machines
If you just want to trial Dorothy commands without configuring your shell, you can do the following:
# IF you are on alpine, install the dependencies apk add curl git bash # IF you are on ubuntu, install the dependencies apt update apt install curl git bash # IF you are on macOS, install the dependencies xcode-select --install # To run only a specific command, run the following and swap out `what-is-my-ip` with whatever command you wish to run bash -ic "$(curl -fsSL https://dorothy.bevry.workers.dev/commands/what-is-my-ip)" # To run multiple commands in a REPL, run the following then type the commands you wish to execute eval "$(curl -fsSL https://dorothy.bevry.workers.dev)"
If your shell doesn't recognise the syntax above, run
bash -il then run the command again.
To install Dorothy run the following in your favorite terminal application:
# IF you are on alpine, install the dependencies apk add curl git bash # IF you are on ubuntu, install the dependencies apt update apt install curl git bash # IF you are on macOS, install the dependencies xcode-select --install # Run the dorothy installation script bash -ilc "$(curl -fsSL https://raw.githubusercontent.com/bevry/dorothy/master/commands/setup-dorothy)"
If your shell doesn't recognise the syntax above, run
bash -il then run the command again.
If you would like to do the installation manually, refer to
During installation, Dorothy will ask you to create a repository to store your user configuration, such as a
dotfiles repository. If you already have a dotfiles repository, you can use that, or make another. If you decide to use your existing dotfiles repository refer to the Configuration section for the expectations.
This will by default install Dorothy to
$HOME/.dorothy, which consists of the following:
commandsdirectory contains executable commands
sourcesdirectory contains scripts that are loaded into the shell environment
themesdirectory contains themes that you can select via the
userdirectory is your own github repository for your custom configuration
init.fishthe initialization script for the fish shell
init.shthe initialization script for other shells
The initialization of Dorothy works as follows:
Fish shell will be instructed to load Dorothy's
init.fishfile, and the other shell's will be instructed to load Dorothy's
The initialization file will set the
DOROTHYenvironment variable to the location of the Dorothy installation, and load the appropriate
sources/extrasfile for our shell.
The essentials will configure the scripting necessities:
- evaluate the output of
setup-paths-commandswhich will setup the various environment variables for what our system has installed (such as adding ecosystem tooling to
PATHand setting up the various
- load our user configuration and overrides
- evaluate the output of
The extras will configure everything needed for user shells, rather than necessarily scripting:
- Configure our editor preferences
- Configure our aliases and functions
- Configure ssh
- Configure zsh
- Configure azure and google cloud
- Configure shell auto-completions
- Configure the theme
All up, this is pretty amazing.
After installing Dorothy, there will now be hundreds of commands available to you, most should be intuitive, and if they receive arguments, then they should alert you to what they are. Soon there will also be man page documentation for these.
The most prominent commands and functionality are grouped into categories below.
Dorothy is highly configurable. During the installation process, it would have set you up with your own
user repository inside Dorothy. You can run
edit "$DOROTHY/user" to open it in your favorite GUI editor. Or if you haven't installed Dorothy yet, you can refer to Benjamin Lupton's dotfiles for his directory.
Inside the user configuration will be a
commands directory, which is automatically inside your
PATH (meaning it is runnable by just typing its name in your terminal). If you have created a new command, ensure it is executable by running
There will also be a
source.bash file and a
source.sh file inside the user configuration. The
source.bash file is where the configuration for our various bash commands will go, such as our
setup-* installation scripts. The
source.sh file is where you will put configuration that is compatible with all your shells, and is for things primarily outside the Dorothy ecosystem.
USER_SHELLSto specify your preferential order of the shell, such that
select-shellwhich is run within
setup-installwill select your favorite shell that is available
- Other configuration is detailed in the various functionality sections.
Examples of the
defaults.bashwhich contains the defaults.
- Benjamin Lupton's
source.bashwhich contains many installation customizations.
DOROTHY_THEMEto specify which cross-shell theme you would like to use, supported themes are:
source.shconfiguration is detailed in the various functionality sections.
To open/edit your
Examples of the
defaults.shwhich contains the defaults.
- Benjamin Lupton's
source.shwhich contains a few shell configurations, as well as loading of a
If you are wanting to migrate your existing dotfiles configuration to Dorothy, you will probably have a legacy setup where instead of commands, you have functions, and instead of being cross-shell compatible, all your functions are written for one particular shell. To level-up your setup dramatically you will want to:
Turn each of these functions into their own command, such that they can be cross-compatible with any shell that calls it, do this by:
Moving the body of each function into their own command file at
$DOROTHY/user/commands/the-command-name, and the shell prefix to the file, e.g.
#!/usr/bin/env bashfor bash,
#!/usr/bin/env zshfor zsh, and
#!/usr/bin/env fishfor fish.
For functions that you want to keep in your shell environment rather than becoming commands, create a
$DOROTHY/user/sources/directory, and store them in there with the appropriate prefix, and include them via your
For anything that modifies paths, or configures ecosystems, check the
setup-paths-commands command to see if Dorothy already handles it for you, if so you can remove it.
To automatically configure and install a brand new system, you can run
setup-install which will go through the various installation scripts for various tooling, and ask you questions about configuring the defaults for your system, and if you wish to install from any backups.
To routinely keep your system up to date with all the latest tooling, you can use
Both of these use your configuration to determine what to install and keep updated.
APK_INSTALLto specify what should be installed/updated with the APK ecosystem
APT_REMOVEto specify what should be removed with the APT (Debian/Ubuntu) ecosystem
APT_ADDto specify what should be installed/updated with the APT (Debian/Ubuntu) ecosystem
SNAP_INSTALLto specify what should be installed/updated with the SNAP (Ubuntu) ecosystem
HOMEBREW_ARCHto specify which architecture the Homebrew ecosystem should be used (only relevant for Apple Silicon machines)
HOMEBREW_INSTALLto specify what should be installed/updated with the Homebrew (Mac) ecosystem
HOMEBREW_INSTALL_SLOWto specify what should be installed/updated with the Homebrew (Mac) ecosystem, for things that take a very long time to install/update
HOMEBREW_INSTALL_CASKto specify what applications should be installed/updated with the Homebrew (Mac) ecosystem
GO_INSTALLto specify what should be installed/updated with the Golang ecosystem
NODE_INSTALLto specify what global dependencies should be installed/updated with the Node (npm/yarn) ecosystem
PYTHON_INSTALLto specify what should be installed/updated with the Python (Pip) ecosystem
RUBY_INSTALLto specify what should be installed/updated with the Ruby (Gem) ecosystem
RUST_INSTALLto specify what should be installed/updated with the Rust (Cargo) ecosystem
SETUP_UTILSto specify what cross-package-manager utilities should be setup
If you would prefer to focus on a specify ecosystem, you the relevant commands are:
setup-linux-*: installs and configures linux
setup-mac-*: installs and configures mac
setup-utilsinstalls and configures their various ecosystems
setup-*-fonts: installs fonts for your specify operating system
setup-bin: installs the CLI commands for the GUI apps you have installed
edit command will open your favorite installed editor automatically:
- in GUI environments (such as your desktop computer and laptop) will open your favorite available GUI editor (such as VSCode, Atom, etc)
- in terminal environments (such as accessing your computer via SSH, or accessing a remote computer that is using Dorothy) will open your favorite available terminal editor (such as vim, nano, etc)
- git prompts, such as confirming a commit message or git tag annotation, are automatically configured to use your favorite editor for your environment
TERMINAL_EDITORSto specify your preferential order of the command line editors, such that
edit(when running over SSH) will use your favorite terminal editor that is installed
GUI_EDITORSto specify your preferential order of the GUI editors, such that
edit(when running inside a desktop environment) will use your favorite GUI editor that is available
This is functionality is initialized via the
setup-editor-commands command which is evaluated via the appropriate
- your user name, email, github preferences are all configured
- your favorite available diff editor is selected
- passwords will be stored securely in the operating system's secure keychain storage, so you don't have to renter them every time
- ssh will be configured, and includes support for krypton if available
- gpg will be configured, and includes support for krypton and keybase if available
GIT_PROTOCOLto specify your preferred protocol when interacting with git repositories (
GIT_DEFAULT_BRANCHto specify your preferred branch name for new repositories (e.g.
GPG_SIGNING_KEYto specify your preferred GPG key
key command will walk you through the management and creation of your gpg keys.
ssh-add-all command will add new ssh keys to your ssh profile, and correct their permissions, ensuring they are correctly loaded from now on
ssh-new command will walk you through the creation of new ssh keys.
git-review command will open your favorite git review editor (e.g. GitHub Desktop, Gitfox, Tower, etc)
git-fix-email command will allow you to make sure that a repository's git history is using the correct emails for the various users that have committed to it.
git-protocol-apply command will ensure the remote you are using for your git repository is configured to the your desired git protocol.
secret command to stop leaking your env secrets to the world when a malicious program sends your shell environment variables to a remote server. Instead,
secret will use 1Password to securely expose your secrets to just the command that needs them. Specifically:
- secrets ares fetched directly from 1Password, with a short lived session
- secrets are cached securely for speed and convenience, only root/sudo has access to the cache (cache can be made optional if you want)
- secrets are not added to the global environment, only the secrets that are desired for the command are loaded for the command's environment only
SECRETSto customize the database location for your Secrets (defaults to
One of the biggest security concerns these days with using the internet, is the leaking, and potential of modification of your DNS queries. A DNS query is what turns
google.com to say
22.214.171.124. With un-encrypted DNS (the default), your ISP, or say that public Wifi provider, can intercept these queries to find out what websites you are visiting, and they can even rewrite these queries, to direct you elsewhere. This is how many public Wifi providers offer their service for free, by selling the data they collect on you, or worse.
The solution to this is encrypted DNS. Some VPN providers already include it within their service, however most don't. And if you have encrypted DNS, then you get the benefits of preventing evesdropping without the need for expensive VPN, and the risk of your VPN provider evesdropping on you.
Dorothy supports configuring your DNS to encrypted DNS via the
setup-dns command, which includes installation and configuration for any of these:
- AdGuard Home
select-dns command lets you easily select your DNS provider out of many popular and secure variations, some even support adult content filtering and adblocking builtin.
flush-dns command lets you easily flush your DNS anytime, any system.
select-hosts command lets you easily select from a variety of HOSTS files for security and privacy, while maintaining your customizations.
source configuration for
DNS_SERVICEto automate selection of which DNS provider to use
source.bash configuration for
DNS_PROVIDERto automate selection of which DNS service you wish to get your DNS Queries from, if you use
env, then you can set
DNS_IPV6SERVERSto the specific servers to use (this is useful if you are using a local AdGuard Home installation that is available on another machine)
If you are a NoFapper, then you can configure
NOFAP_DISCORD_WEBHOOK_AUTHto ensure your DNS prevents adult content, and alert your mates via the webhook if you are attempting to bypass it
down command will use the best downloader app that you currently have available for performing the download. Very useful for cross-system compatibility, as well as for resuming downloads. Supported apps are
macos-state command for backup and restore of your various application and system preferences, from time machine backups, local directories, and sftp locations. This makes setting up clean installs easy, as even the configuration is automated. And it also helps you never forget an important file, like your env secrets ever again.
macos-drive command is for easily turning a MacOS installer download into a bootable MacOS installer USB drive.
sparse-vault command lets you easily, and for free, create secure encrypted password-protected vaults on your mac, for securing those super secret data.
itunes-owners command will generate a table of who legally owns what inside your iTunes Media Library — which is useful for debugging certain iTunes Store authorization issues, which can occur upon backup restorations.
ios-dev command lets you easily open the iOS simulator from the terminal.
podcast command will convert an audio file to a new file with Apple's recommended podcast encoding and settings
aac-he, which is super optimized for podcast use cases with tiny file sizes and the same quality.
podvideo command will convert a video file to a new file with h264+aac encoding.
ytd-helper command provides some additional flags to make using
video-merge command will merge multiple video files in a directory together into a single video file.
expand-path command will output the results of glob patterns each on their own line.
ok command will execute the command and always return a success exit code, in a way that is cross-shell compatible.
silent command and its
silent-* variants, will hide the various outputs of a command, in a way that is cross-shell compatible.
Any plenty more for cross-shell scripting with the following namespaces:
mail-sync command will move everything from one IMAP provider to another IMAP provider.
pdf-decrypt command will mass decrypt encrypted PDFs and store their results.
xps2pdf command will convert a legacy XPS document into a modern PDF document.
There are hundreds more commands, so you can check them out or carry on knowing that when the time comes, Dorothy probably already has it.
Public Domain via The Unlicense
This is free and unencumbered software released into the public domain. Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means. In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. For more information, please refer to <http://unlicense.org>