🧪 Potions

One command. Powerful dev environment. Any platform.

Potions transforms your fresh macOS, WSL, Termux, or Fedora installation into a fully-configured development environment in minutes.

✨ Features

• Cross-Platform: macOS, WSL (Windows), Termux (Android), Debian/Linux, Fedora
• Pre-configured Tools: Zsh, Git, NeoVim, Zellij, and more
• One-Switch Theming: WCAG-AAA Alchemist's Orchid palette across shell, NeoVim, Zellij, and your terminal — switch or cycle with potions theme
• First-class Terminals: Ghostty (Linux/macOS) and Termux (Android) wired automatically, with live theme changes
• Professional CLI: Manage your installation with potions commands
• Plugin System: Extend functionality with custom plugins
• User Customization: Preserved settings that survive upgrades

🚀 Quick Start

One-Line Installation

curl -fsSL https://raw.githubusercontent.com/Rynaro/potions/main/drink.sh | bash

After installation, restart your terminal or type zsh to begin using your new environment!

🛠️ What's Installed

• Zsh: Modern shell with autosuggestions and syntax highlighting
• Git: Pre-configured with useful aliases
• NeoVim: Powerful editor with modern plugins
• Zellij: Terminal multiplexer with intuitive keybindings
• Development Tools: curl, wget, OpenVPN, and more

💻 CLI Commands

Potions includes a professional CLI for managing your installation:

potions upgrade          # Upgrade to latest version
potions update           # Check for updates
potions version          # Show current version
potions status           # Show installation status
potions info             # Show system information
potions doctor           # Run health check
potions help             # Show help message

potions theme cycle      # Cycle the colorscheme (dark | white | sepia)
potions theme set alchemists-orchid white
potions terminal setup   # Wire detected terminals (Ghostty/Termux)
potions terminal status  # Show detected emulators and wiring

potions reload           # Re-apply config everywhere (regenerate + live-push)
potions reload terminal  # Re-apply terminal surfaces only (= potions terminal reload)

Theming & Terminals

Potions ships the Alchemist's Orchid palette (WCAG-AAA, astigmatism-friendly) as one source of truth across the shell, NeoVim, Zellij, and your terminal emulator. Ghostty (Linux/macOS) and Termux (Android) are configured automatically — palette, cursor/selection, and quality-of-life settings — with live theme switching. See the Terminal Setup Guide.

potions reload re-applies your current config across every surface in one command: it regenerates all artifacts, then live-pushes wherever it safely can (the current terminal's palette via OSC, Termux via termux-reload-settings, Kitty when remote control is on). Surfaces that can't be hot-reloaded from outside (Zellij, NeoVim, Ghostty) are reported with the exact one-line action to finish. Scope it with potions reload [all|terminal|shell|nvim|zellij]; potions terminal reload is shorthand for the terminal surfaces. Nothing ever hangs and nothing is over-promised — the printed status matrix is the truth.

📝 Configuration

All configurations are stored in ~/.potions:

Managed Files (Do Not Edit)

These files are overwritten on upgrade:

• .zshrc - Main Zsh configuration
• nvim/init.vim - NeoVim configuration
• zellij/config.kdl - Zellij configuration

User Customization (Preserved on Upgrade)

Add your customizations here—they survive upgrades:

File	Purpose
config/aliases.zsh	Custom aliases and functions
config/secure.zsh	Private configurations (gitignored)
config/local.zsh	Machine-specific settings
config/{macos|linux|wsl|termux}.zsh	Platform-specific customizations
nvim/user.vim	Your Neovim extensions
zellij/user.kdl	Your Zellij extensions

Legacy Files (Still Supported)

• .zsh_aliases - Legacy aliases (use config/aliases.zsh instead)
• sources/*.sh - Legacy platform configs (use config/*.zsh instead)

Run ./migrate.sh to migrate from legacy to new structure.

⌨️ Keybindings Quick Reference

Zellij (Prefix: Ctrl+a)

macOS users: The prefix is Ctrl+a (hold Control, press A) — not Cmd+A. Cmd+A triggers "Select All" in your terminal and never reaches Zellij. See the Terminal Setup Guide for macOS-specific setup.

Key	Action	macOS Notes
Ctrl+a c	New tab	or Alt+t
Ctrl+a x	Close pane	or Alt+w
Ctrl+a |	Split right	or Alt+d
Ctrl+a -	Split down	—
Ctrl+a h/j/k/l	Navigate panes	or Alt+h/j/k/l
Ctrl+a n	Next tab	or Alt+n
Ctrl+a p	Previous tab	or Alt+p
Ctrl+a z	Toggle fullscreen	or Alt+Enter
F1	Open cheatsheet	Works everywhere, no setup
Ctrl+Tab	Next tab	Not forwarded by Terminal.app — use Alt+n

Neovim (Leader: Space)

Key	Action
Ctrl+n	Toggle NERDTree file explorer
Space ff	Find files (Telescope)
Space fg	Live grep
Space fb	Find buffers
Space 1-9	Go to buffer N
Space q	Quit
Space w	Save
Ctrl+s	Quick save

📖 Full reference: .potions/KEYMAPS.md

🔌 Plugin System

# Install plugins
echo "Rynaro/mini-rails" > plugins.txt
./plugins.sh install

# Create your own plugin
./plugins.sh create my_awesome_plugin

🧪 Test Mode

Test the installation interface without modifying your system:

./install.sh --test
./drink.sh --test

🔄 Upgrading

Using CLI (Recommended)

potions upgrade

Manual Upgrade

curl -fsSL https://raw.githubusercontent.com/Rynaro/potions/main/upgrade.sh | bash

The upgrade script:

• ✅ Creates automatic backups in ~/.potions/backups/ (keeps last 5)
• ✅ Preserves user customizations in config/*.zsh and user files
• ✅ Updates configuration files with latest improvements

After upgrading, restart your terminal or run exec zsh to apply changes.

🔧 Troubleshooting

Terminal Key Bindings Not Working

Some terminals require configuration for certain key combinations. See the Terminal Setup Guide for:

• iTerm2 configuration
• Alacritty settings
• Terminal.app workarounds

Common Issues

Issue	Solution
Tmux mode (Ctrl+a) does not activate on macOS	You may be pressing Cmd+A (⌘A) instead of Ctrl+a. Use cat -v to verify.
Ctrl+Tab not working	Use Alt+n or Ctrl+a n; or configure terminal (see Terminal Setup Guide)
Cmd+D/T/W does nothing in Zellij	These are intercepted by macOS. Use Alt+d/t/w or configure Cmd→Alt forwarding
Word navigation broken	Check terminal key mappings, try Alt+f/Alt+b
Ctrl+S freezes terminal	Potions disables this automatically (stty -ixon in .zshrc); if it persists in a non-Potions shell, run stty -ixon

🗑️ Uninstalling

To remove Potions while preserving your customizations:

curl -fsSL https://raw.githubusercontent.com/Rynaro/potions/main/uninstall.sh | bash

🤝 Contributing

Contributions welcome! Help improve Potions by submitting bug reports, improving documentation, adding platform support, or creating plugins.

📜 License

MIT License