Dorothy

Dorothy is a dotfile ecosystem featuring:

• seamless support for Bash, Zsh, Fish, Nu, Xonsh, Elvish, Dash, KSH
• 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

Introduction

Watch the 2023 November Presentation to see what Dorothy can do!

Setup

Supported Platforms

Other platforms may or may not be supported. Mageia, Nix, Gentoo are unsupported.

Prerequisites

macOS:

xcode-select --install

Windows 10/11:

# [Install WSL.](https://learn.microsoft.com/en-au/windows/wsl/install)
wsl --install
wsl --set-default-version 2
# note that [wsl --version] does not report WSL2, you need to do [wsl -l -v]

Ubuntu / Debian / Kali:

sudo apt-get update
sudo apt-get install bash curl

Fedora:

dnf check-update
dnf --refresh --best install bash curl

OpenSUSE / SUSE:

zypper --gpg-auto-import-keys refresh
zypper install bash curl

Alpine:

doas apk update
doas apk add bash curl grep

Manjaro:

pamac install bash curl

Arch:

pacman-key --init
pacman --refresh --sync --needed bash curl

Void:

xbps-install --sync --update xbps
xbps-install --sync bash curl

Try

You can trial Dorothy commands without configuring your shell.

To run a specific command in/from the Dorothy environment, enter the following, swapping out everything after the double-dash (--) with whatever command to run:

bash -ic "$(curl -fsSL https://dorothy.bevry.me/run)" -- echo-verbose -- a b c
# if your shell doesn't recognize any of the above syntax, run `bash -i` then try again

To run multiple commands in/from a Dorothy-configured REPL, enter the following line by line:

bash -ic "$(curl -fsSL https://dorothy.bevry.me/repl)"
# if your shell doesn't recognize any of the above syntax, run `bash -i` then try again

# now you can run whatever and how many commands as you'd like, such as:
echo-verbose -- a b c
echo-style --success=awesome

# once you are done, exit the trial environment
exit

Install

To install Dorothy enter the following in your favorite terminal application:

bash -ic "$(curl -fsSL https://dorothy.bevry.me/install)"
# if your shell doesn't recognize any of the above syntax, run `bash -i` then try again

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.

Verify the installation worked by selecting a theme for Dorothy by running:

# you must open a new terminal instance first
dorothy theme
# then open a new terminal

To select your login shell, run setup-shell.

Troubleshooting

If packages are failing to install, go back to the "Prerequisites" section.

If your shell doesn't recognize any of the Dorothy commands (you get a command not found error, or an undefined/unbound variable error), then it could be that:

• Your shell is not running as a login shell. Verify that your Terminal is running the shell as a login shell.
• Dorothy did not configure itself for the shell you use. Re-run the Dorothy installation process, and be sure to configure Dorothy for your shell.
• Your login shell is not one of the Dorothy supported shells. Create an issue requesting support for your shell.

If you see unrecognised symbols, you probably require fonts. Once Dorothy is loaded, run setup-util-noto-emoji which installed Noto Emoji, a font for enabling emojis inside your terminal. For rendering glyphs, run setup-util-nerd-fonts which will prompt you for which Nerd Font to install. You may need to update your terminal preferences the installed fonts.

Overview

Dorothy Core

Dorothy installs itself to $DOROTHY, which defaults to the XDG location of ~/.local/share/dorothy, and consists of the following:

• commands directory contains executable commands of super-stable quality, they are actively used within the Dorothy core and by the users of Dorothy.
• commands.beta directory contains executable commands of beta quality, these are commands that require more usage or possible breaking changes before promotion to commands.
• config directory contains default configuration
• sources directory contains scripts that are loaded into the shell environment
• themes directory contains themes that you can select via the DOROTHY_THEME environment variable
• user directory is your own github repository for your custom configuration

For each shell that you configured during the Dorothy installation (can be reconfigured via the dorothy install command), the configured shell performs the following steps when you open a new shell instance via your terminal:

1. The shell loads Dorothy's initialization script:

   • Elvish loads our init.elv script
   • Fish loads our init.fish script
   • Nu loads our init.nu script
   • Xonsh loads our init.xsh script
   • POSIX shells (Bash, Zsh, Dash, KSH, etc) load our init.sh script

2. The initialization script will:

   1. Ensure the DOROTHY environment variable is set to the location of the Dorothy installation.

   2. If a login shell, it loads our login script sources/login.(bash|dash|elv|fish|ksh|nu|xsh|zsh), which will:

      1. Apply any configuration changes necessary for that login shell

      2. Load our environment script sources/environment.(bash|dash|elv|fish|ksh|nu|xsh|zsh), which will:

         1. Invoke commands/setup-environment-commands which determines and applies all necessary environment configuration changes to the shell. It loads your user/config(.local)/environment.bash configuration script for your own custom environment configuration that will be applied to all your login shells.

   3. If a login and interactive shell, it loads our interactive script sources/interactive.(bash|dash|elv|fish|ksh|nu|xsh|zsh), which will:

      1. Load your own user/config(.local)/interactive.(sh|bash|dash|elv|fish|ksh|nu|xsh|zsh) configuration script for your own interactive login shell configuration.
         • Elvish will only load interactive.elv if it exists.
         • Fish will load interactive.fish if it exists, otherwise it will load interactive.sh.
         • Nu will only load interactive.nu and it must exist.
         • Xonsh will only load interactive.xsh if it exists.
         • POSIX shells (Bash, Zsh, Dash, KSH, etc) will load their interactive.(bash|zsh|...etc) file if it exists, otherwise they will load interactive.sh if exists.
      2. Load any common alias and function utilities.
      3. Load our theme configuration.
      4. Load our ssh configuration.
      5. Load our autocomplete configuration.

This is the foundation that enables Dorothy's hundreds of commands to work across hundreds of machines, across dozens of operating system and shell combinations, seamlessly.

Dorothy User Configuration

Your user configuration goes to the XDG location of ~/.local/config/dorothy which Dorothy symlinks to ~/.local/share/dorothy/user, your user configuration consists of the following:

• commands directory, for public commands
• commands.local directory, for private commands (git ignored by default)
• config directory, for public configuration
• config.local directory, for private configuration (git ignored by default)

The order of preference within Dorothy is (commands|config).local first, then (commands|config), then Dorothy's own (commands|config) then everything else.

You can find the various configuration files that are available to you by browsing Dorothy's default config directory.

Showcase

Use these sources to find inspiration for your own user commands and configuration.

• Dorothy's commands directory for super-stable commands with up to date conventions.
• Dorothy's commands.beta directory for beta-quality commands with possibly outdated conventions.
• Dorothy's docs directory containing tips and tricks for Dorothy, and various shells, such as enabling private user configurations, and the manual to assisted philosophy of Dorothy
• Dorothy User Configurations:
  • @balupton / dotfiles: uses Fish as login shell, plenty of Bash commands
  • @molleweide / dotfiles: uses Zsh as login shell, plenty of Bash commands, kmonad user
  • @jondpenton / dotfiles: uses Nu as login shell, plenty of Nu commands
  • if you use Dorothy, send a pull request to add your own user configuration to this list.

After installing Dorothy, there will now a plethora of commands available to you. You can invoke any stable command with --help to learn more about it. The most prominent commands are noted below.

Stable commands:

• setup-system

  • setup-system install correctly setup your system to your prompted preferences
  • setup-system update correctly update your system to your existing preferences

  This is done via these commands:

  • setup-linux correctly setup your Linux system, and its various packaging systems, as desired

  • setup-mac correctly setup your macOS system, including its homebrew and Mac App Store installations, as desired

  • setup-bin correctly setup available CLI utilities from installed GUI Applications

  • setup-git correctly setup Git on your system, including your profile, SSH, GPG, and 1Password configurations, as desired.

    Related commands:

    • gpg-helper interact with your GPG keys
    • ssh-helper interact with your SSH keys

  • setup-go correctly setup GoLang on your system if desired or if required for your desired packages

  • setup-node correctly setup Node.js on your system if desired or if required for your desired packages

  • setup-python correctly setup Python on your system if desired or if required for your desired packages

  • setup-ruby correctly setup Ruby on your system if desired or if required for your desired packages

  • setup-rust correctly setup Rust on your system if desired or if required for your desired packages

  • setup-utils correctly setup your selected setup-util-* utilities as desired

• setup-util is an intelligent wrapper around every package system, allowing a cross-compatible way to install, upgrade, and uninstall utilities.

  It is used by the hundreds of setup-util-* commands, which enable installing a utility as easy as invoking setup-util-<utility>

  If you don't know which command you need to call, you can use get-installer to get which command you will need to invoke to install a utility/binary/application.

• setup-shell correctly configure your desired shell to be your default shell.

  By default, your terminal application will use the login shell configured for the system, as well as maintain a whitelist of available shells that can function as login shells.

• edit quickly open a file in your preferred editor, respecting terminal, SSH, and desktop environments.

• down download a file with the best available utility on your computer.

• github-download download files from GitHub without the tedium.

• secret stops you from 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 are 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

• setup-dns correctly configures your systems DNS to your preferences

  A large security concern these days of using the internet, is the leaking, and potential of modification of your DNS queries. A DNS query is what turns google.com to say 172.217.167.110. 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 eavesdropping without the need for expensive VPN, and the risk of your VPN provider eavesdropping 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
  • Cloudflared
  • DNSCrypt

  Related commands:

  • flush-dns lets you easily flush your DNS anytime, any system.
  • setup-hosts lets you easily select from a variety of HOSTS files for security and privacy, while maintaining your customizations.

• mount-helper lets you easily, correctly, and safely mount, unmount, automount, various devices, filesystems, network shares, gocryptfs vaults, etc, on any system.

  Related commands:

  • get-devices cross-platform fetching and filtering of select and complete device information
  • gocryptfs-helper helpers for GoCryptFS
  • what-is-using find out what is using a path so that you can unmount it safely

• Dorothy also provides commands for writing commands, such as:

  • bash.bash for a Bash strict mode that actually works, and various shims/polyfills
  • ask, confirm, and choose for prompting the user for input
  • echo-style, echo-segment, echo-element, echo-error, echo-verbose, and eval-helper for output styling
  • Dozens of echo-*, fs-*, get-*, and is-* helpers

Beta commands:

• mail-sync helps you migrate all your emails from one cloud provider to another.

macOS

Stable commands:

• alias-helper helps you manage your macOS aliases, and if desired, convert them into symlinks.
• macos-drive helps you turn a macOS installer into a bootable USB drive.
• macos-installer fetches the latest macOS installer.
• sparse-vault lets you easily, and for free, create secure encrypted password-protected vaults on your mac, for securing those super secret data.

Beta commands:

• eject-all eject all removable drives safely.
• icloud-helper can free up space for time machine by evicting local iCloud caches.
• itunes-owners generates 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.
• macos-settings helps configure macOS to your preferred system preferences.
• macos-state helps you backup and restore 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-theme helps you change your macOS theme to your preference, including your wallpaper and editor.
• tmutil-helper can free up space for bootcamp by evicting local Time Machine caches.

media

Beta commands:

• convert-helper convert one media format to another
• get-codec gets the codec of a media file
• is-audio-mono checks if an audio file is mono
• is-audio-stereo checks if an audio file is stereo
• pdf-decrypt will mass decrypt encrypted PDFs.
• pdf-decrypt decrypts a PDF file
• svg-export converts an SVG image into a desired image format
• video-merge will merge multiple video files in a directory together into a single video file.
• wallhaven-helper download your wallpaper collections from Wallhaven
• xps2pdf will convert a legacy XPS document into a modern PDF document.
• ytd-helper helps you download videos from the internet with simplified options.

Community

Join the Bevry Software community to stay up-to-date on the latest Dorothy developments and to get in touch with the rest of the community.

Backers

Code

Discover how to contribute via the CONTRIBUTING.md file.

Authors

• Benjamin Lupton — Accelerating collaborative wisdom.

Maintainers

• Benjamin Lupton — Accelerating collaborative wisdom.

Contributors

• Benjamin Lupton — view contributions
• Bevry Team — view contributions
• BJReplay — view contributions
• molleweide — view contributions
• Nutchanon Ninyawee — view contributions
• Sumit Rai — view contributions

Finances

Sponsors

• Andrew Nesbitt — Software engineer and researcher
• Codecov — Empower developers with tools to improve code quality and testing.
• Frontend Masters — The training platform for web app engineering skills – from front-end to full-stack! 🚀
• Poonacha Medappa
• Rob Morris
• Sentry — Real-time crash reporting for your web apps, mobile apps, and games.
• Syntax — Syntax Podcast

Donors

• Andrew Nesbitt
• Balsa
• Chad
• Codecov
• entroniq
• Frontend Masters
• Jean-Luc Geering
• Michael Duane Mooring
• Mohammed Shah
• Mr. Henry
• Poonacha Medappa
• Rob Morris
• Sentry
• ServieJS
• Syntax

License

Unless stated otherwise all works are:

• Copyright © Benjamin Lupton

and licensed under:

• Reciprocal Public License 1.5