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

Operating System	Architecture	Support
🍏 macOS	🍏 Apple Silicon (ARM64)	🤖 CI
🍏 macOS	👔 Intel/AMD (x86_64)	🤖 CI
🍓 Raspberry Pi OS: Desktop, Lite	🍓 Raspberry Pi (ARM64)	🤖 CI
🪟 Windows 10/11 WSL2: Ubuntu, Debian, AlmaLinux, Kali	👔 Intel/AMD (x86_64)	🤖 CI
👐 AlmaLinux	👔 Intel/AMD (x86_64)	🤖 CI
👐 AlmaLinux on Raspberry Pi	🍓 Raspberry Pi (ARM64)	🤖 CI
▲ Arch	👔 Intel/AMD (x86_64)	🤖 CI
CachyOS	👔 Intel/AMD (x86_64)	🤖 CI
꩜ Debian	👔 Intel/AMD (x86_64)	🤖 CI
꩜ Debian on Raspberry Pi	🍓 Raspberry Pi (ARM64)	🤖 CI
💫 Devuan	👔 Intel/AMD (x86_64)	🤖 CI
𝓮 elementary OS	👔 Intel/AMD (x86_64)	🤖 CI
∞ Fedora: Workstation, Server	👔 Intel/AMD (x84_64)	🤖 CI
∞ Fedora on Raspberry Pi: Workstation, Server	🍓 Raspberry Pi (ARM64)	🤖 CI
🐉 Kali	👔 Intel/AMD (x84_64)	🤖 CI
🐉 Kali on ARM	🍓 Raspberry Pi (ARM64)	🤖 CI
OpenEuler	👔 Intel/AMD (x84_64)	🤖 CI
OpenEuler on Raspberry Pi	🍓 Raspberry Pi (ARM64)	🤖 CI
❍ OpenMandriva: Rock, Rolling	👔 Intel/AMD (x86_64)	🤖 CI
🦎 OpenSUSE: Leap, Tumbleweed	👔 Intel/AMD (x84_64)	🤖 CI
🦎 OpenSUSE on Raspberry Pi: Leap, Tumbleweed	🍓 Raspberry Pi (ARM64)	🤖 CI
⭕️ Ubuntu: Desktop, Server	👔 Intel/AMD (x86_64)	🤖 CI
⭕️ Ubuntu on Raspberry Pi: Desktop, Server	🍓 Raspberry Pi (ARM64)	🤖 CI
⭐ Vanilla	👔 Intel/AMD (x86_64)	🤖 CI

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

Dependencies

Dorothy has intelligent dependency management with its own setup-util command and setup-util-* ecosystem, that automates and assists dependency and package availability across platforms, architectures, and package systems.

Dependencies that are required to achieve your intended goal, will have their installations initiated correctly. Dependencies that are not required, but provide a superior experience, will have their installations attempted but if an installation fails or is unavailable, the command will not dazzle but will still execute successfully to satisfaction. Sometimes commands can go an extra mile if a dependency is detected, such as for performance or gathering additional optional information, however, if an already suitable dependency is already available then the suitable installed dependency will be used. This enables Dorothy to provide extreme robustness and superiority of its experience.

For instance, installing curl with Dorothy is as easy as executing setup-util-curl, or directly by setup-util --cli=curl APK=curl APT=curl AUR=curl BREW=curl RPM=curl WINGET=cURL ZYPPER=curl. If you want to make it optional, add --optional. If you want to write a command that prefers curl but also supports wget if curl isn't present, see Dorothy's fetch command, or for something even more powerful, see Dorothy's down command.

Prerequisites

Important

To initiate Dorothy, some prerequisite dependencies are required:

macOS:

xcode-select --install

Windows 10/11:

# https://learn.microsoft.com/en-au/windows/wsl/install
wsl.exe --install --no-distribution
# wsl.exe --set-default-version 2
wsl.exe --list --online
wsl.exe --install # -d Debian
# wsl.exe --set-default Debian
wsl.exe --list --verbose
# wsl.exe --unregister Debian # do not use --uninstall, that removes WSL

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

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

Requisites

Now that the prerequisites are installed, Dorothy's intelligent dependency management will be enabled, so you can skip this section. Dorothy's complete requisites for its core experience are as follows:

• bash, curl: required prior to initiation of the Dorothy installer
• grep, git, awk: guaranteed by the Dorothy installer, and used to to install Dorothy
• jq, deno: guaranteed by Dorothy, for robust regular expressions and configuration management

If the automated installation of any failed, post an issue including details of your environment, and use their links for alternative installation methods. If you are downloading their binaries straight from GitHub, you can unzip with tar -xvf <archive>, make a discoverable binary directory with mkdir -p -- ~/.local/bin, move the binary there with mv -- <bin> ~/.local/bin, and make the binaries executable with chmod +x ~/.local/bin/*.

Try

Tip

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 -i # in case your shell doesn't recognize the next command
bash -ic "$(curl -fsSL https://dorothy.bevry.me/run)" -- dorothy commands

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

bash -i # in case your shell doesn't recognize the next command
bash -ic "$(curl -fsSL https://dorothy.bevry.me/repl)"

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

# once you are done, exit the trial environment
exit

Install

Important

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

bash -i # in case your shell doesn't recognize the next command
bash -ic "$(curl -fsSL https://dorothy.bevry.me/install)"

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.

Once installation has completed, open a new terminal instance such that Dorothy is loaded with the new configuration applied. In the new terminal instance, verify the installation and configuration was successful by running dorothy commands, which will list all the Dorothy commands available to you.

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 installs 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 to leverage these installed fonts.

If you are using Visual Studio Code, due to a #wontfix bug in their terminal rendering you will need "terminal.integrated.minimumContrastRatio": 1 in your settings to fix background colours disabling foreground colours (this is automatically applied to the dorothy edit workspace). Visual Studio Code also has another #wontfix bug where tab characters are converted to spaces, preventing their copying, without a workaround.

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
     • KSH and Dash first load their respective init.ksh and init.dash scripts before loading init.sh. This is because KSH, Dash, and Bash all share the same .profile configuration file, so different initialization scripts allow us to configure each of them independently.

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 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 Bash 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
  • See more Dorothy User Configurations
  • To feature your own Dorothy User Configuration, send a pull request.

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-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:

• fs-alias 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
• Cœur — view contributions
• Joel McCracken — view contributions
• molleweide — view contributions
• Nutchanon — view contributions
• Octavian — view contributions
• Oscar Vargas Torres — view contributions
• Sam Gutentag — view contributions
• Sumit Rai — view contributions

Finances

Sponsors

• Andrew Nesbitt — Working on mapping the world of open source software @ecosyste-ms and empowering developers with @octobox
• Canonical
• Divinci ™ — A more comfortable AI conversation experience, with friends! 🤖🖤
• Edward J. Schwartz
• Frontend Masters — The training platform for web app engineering skills – from front-end to full-stack! 🚀
• Poonacha Medappa
• Roboflow

Donors

• Andrew Nesbitt
• Ángel González
• Arjun Aditya
• Armen Mkrtchian
• Balsa
• Canonical
• Chad
• Codecov
• Divinci ™
• dr.dimitru
• Edward J. Schwartz
• Elliott Ditman
• entroniq
• Frontend Masters
• GitHub
• Hunter Beast
• Jean-Luc Geering
• Lee Driscoll
• Michael Duane Mooring
• Michael Harry Scepaniak
• Mr. Henry
• Pleo
• Poonacha Medappa
• Robert de Forest
• Rob Morris
• Roboflow
• Scott Kempson
• Sentry
• ServieJS
• Shah
• Skunk Team
• Square
• Syntax
• WriterJohnBuck

License

Unless stated otherwise all works are:

• Copyright © Benjamin Lupton

and licensed under:

• Reciprocal Public License 1.5