Skip to content

README.md

Latest commit

 

History

History
217 lines (155 loc) · 7.6 KB

README.md

File metadata and controls

217 lines (155 loc) · 7.6 KB
Raw

🧪 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