Franklin is a cozy Zsh shell setup inspired by the cartoon turtle you probably read about as a kid. He keeps your shell lightweight, consistent, and portable. macOS and Linux installs auto-detect the right package manager (brew/apt/dnf) so each flavor gets the correct fit.

curl -fsSL https://raw.githubusercontent.com/jeremyfuksa/franklin/main/franklin/src/bootstrap.sh | bash

Pin a specific version and install path:

curl -fsSL https://raw.githubusercontent.com/jeremyfuksa/franklin/main/franklin/src/bootstrap.sh \
  | bash -s -- --dir "${HOME}/.local/share/franklin" --ref v2.0.0-beta-1

That's it—Franklin downloads his shell and gently asks about your preferred color palette along the way.

Need automation? Use the flags below.

Franklin signature color names (Campfire palettes): clay, flamingo, terracotta, ember, golden-amber, hay, sage, moss, pine, cello, blue-calx, dusk, mauve-earth, stone. You can pin ember:clay, ash:cello, or any #rrggbb.

Prefer cloning?

git clone https://github.com/jeremyfuksa/franklin ~/.config/franklin
cd ~/.config/franklin
bash install.sh

Everything lives under your install dir (default ~/.local/share/franklin) with configs in ~/.config/franklin. The installer detects your OS (macOS, Debian/Ubuntu, Fedora, or any Linux with apt/dnf) and runs the appropriate setup. Before touching your existing setup, it backs up .zshrc, .zshenv, .zprofile, your sheldon config, and ~/.config/starship.toml to ~/.local/share/franklin/backups/<timestamp>.

Franklin is designed to be customized. Here’s how you can make it your own.

The best way to add your own aliases, functions, and PATH adjustments is by editing ~/.franklin.local.zsh. This file is loaded by Franklin's .zshrc but isn't managed by Franklin itself, so your changes won't be overwritten during updates.

The installer creates this file for you with some common examples to get you started.

To add custom shell plugins, edit ~/.config/sheldon/plugins.toml and then run sheldon lock.

The prompt is powered by Starship. You can customize it by editing ~/.config/starship.toml.

• Banner Color: Change the color of the Franklin banner with franklin config --color <name|#hex>. You can also edit ~/.config/franklin/config.env directly. Franklin's signature colors are clay, flamingo, terracotta, ember, golden-amber, hay, sage, moss, pine, cello, blue-calx, dusk, mauve-earth, and stone.

• MOTD Services: To monitor systemd or launchd services in the MOTD dashboard, add their names to the MONITORED_SERVICES variable in ~/.config/franklin/config.env. Docker containers are detected automatically.

  # ~/.config/franklin/config.env
  MONITORED_SERVICES="nginx,postgresql,redis"

• Disable MOTD: To prevent the MOTD from showing on login, set FRANKLIN_SHOW_MOTD_ON_LOGIN=0 in ~/.franklin.local.zsh.

• Update Behavior: Control the default mode for update-all.sh by creating ~/.config/franklin/update.env.

  # ~/.config/franklin/update.env
  FRANKLIN_UPDATE_MODE=quiet # quiet, auto, or verbose
  FRANKLIN_UPDATE_TIMEOUT=600

• Backup Location: To change where Franklin stores backups of your old dotfiles, set the FRANKLIN_BACKUP_DIR environment variable before running the installer.

  export FRANKLIN_BACKUP_DIR=/path/to/your/backups
  # ... then run the installer

• Local Overrides File: If you want to store your local overrides in a different location than ~/.franklin.local.zsh, set the FRANKLIN_LOCAL_CONFIG environment variable in your .zshenv file.

Working on Franklin itself (not just using it)?

# Bootstrap smoke test (uses a GitHub-style archive from HEAD)
bash test/bootstrap-tests.sh

# Legacy installer tests (macOS-oriented)
bash test/test_install.sh

See CONTRIBUTING.md for coding style, release expectations, and PR guidelines.

For v2.x, releases are tagged and published on GitHub:

1. Ensure CHANGELOG.md has the new entry.
2. Update VERSION and pyproject.toml.
3. Tag (vX.Y.Z) and push; draft the GitHub release from the tag with summary notes.

MIT License. Check out the source at github.com/jeremyfuksa/franklin.

Franklin stands on the shoulders of:

• Sheldon for plugin management
• Starship for the prompt
• NVM for Node versioning