🚀 Pi Bootstrap

A streamlined, opinionated development environment bootstrap for Raspberry Pi devices. Deploys a modern Zsh configuration with powerful plugins, beautiful prompts, and essential development tools.

✨ Features

Shell & Terminal

• Zsh with optimized history and keybindings
• Powerlevel10k - Fast, flexible, and beautiful prompt theme
• Znap - Blazing fast Zsh plugin manager
• fzf - Fuzzy finder for command history and file search
• zoxide - Smarter cd command that learns your habits
• eza - Modern ls replacement with icons and colors

Plugins

• zsh-autosuggestions - Fish-like autosuggestions
• zsh-completions - Additional completion definitions
• zsh-syntax-highlighting - Real-time syntax highlighting
• fzf-tab - Tab completion with fzf integration
• you-should-use - Reminds you of existing aliases
• Oh My Zsh plugins: git, command-not-found

📋 Prerequisites

• A Raspberry Pi running Raspberry Pi OS (tested on Trixie/Debian 13)
• SSH access to the Pi
• Python 3.10+ on your local machine
• Network connectivity between your machine and the Pi

🚀 Quick Start

1. Set up SSH keys (recommended)

ssh-copy-id user@raspberry-pi-ip

This avoids multiple password prompts during deployment.

2. Deploy to your Raspberry Pi

python3 deploy.py user@raspberry-pi-ip

Replace user with your Pi username and raspberry-pi-ip with your Pi's IP address or hostname.

3. Log out and back in

After deployment completes, log out and log back into your Pi:

ssh user@raspberry-pi-ip

On first login, the Powerlevel10k configuration wizard will start automatically.

📁 Project Structure

Pi-Bootstrap/
├── deploy.py          # Main deployment script
├── revert.py          # Script to revert changes
├── unstrap.sh         # The remote revert script
├── pyproject.toml     # Python project configuration
├── README.md          # This file
└── payloads/
    ├── setup.sh       # Remote setup script
    └── .zshrc         # Zsh configuration file

🔧 What Gets Installed

System Packages

• zsh
• git
• curl
• fzf (fuzzy finder)
• zoxide (smart cd)
• eza (modern ls)
• tmux (terminal multiplexer)
• vim (text editor)
• bat (cat with syntax highlighting)

Directory Structure

~/
├── repos/
│   ├── znap/                  # Zsh plugin manager
│   ├── ohmyzsh/oh-my-zsh/     # Oh My Zsh framework
│   └── [other plugins]/        # Automatically managed by Znap
└── .zshrc                     # Your new shell configuration

🎨 Customization

Changing the Theme

To reconfigure Powerlevel10k:

p10k configure

Adding More Plugins

Edit payloads/.zshrc and add plugins using Znap syntax:

znap source username/repo-name

Then redeploy or manually source the file:

source ~/.zshrc

Custom Aliases

Your aliases are defined in .zshrc. Current aliases include:

File Operations:

• ls, ll, la - Enhanced listing with eza
• lt, lt1, lt2, lt3 - Tree views at different depths
• lta, lta1, lta2, lta3 - Tree views including hidden files

Raspberry Pi Specific:

• temp - Check CPU temperature
• gpio - Display GPIO pinout

Development:

• reload - Reload Zsh configuration

🔍 Deployment Details

Interactive vs Automated Mode

With SSH Keys:

• Clean progress bars and minimal output
• No password prompts
• Recommended for regular use

Without SSH Keys:

• Shows detailed output
• Prompts for password 5 times (remove, create dir, upload, setup, cleanup)
• Good for first-time setup or debugging

Deployment Steps

1. Cleanup - Removes old Oh My Zsh directory to prevent conflicts
2. Create temp directory - Stages files for deployment
3. Upload - Transfers configuration files via SCP
4. Setup - Runs remote setup script with interactive prompts
5. Cleanup - Removes temporary files

🛠️ Troubleshooting

"znap source: file not found"

This has been fixed in the latest version. If you see this error, ensure you're using the updated .zshrc file.

Shell doesn't change to Zsh

The setup script changes your default shell, but you need to log out and back in for it to take effect. Alternatively, restart your Pi.

Plugins not loading

Run this to manually update plugins:

znap pull

Permission denied errors

Ensure your user has sudo privileges on the Pi.

🔄 Updating

To update your bootstrap configuration:

1. Edit files locally in the payloads/ directory
2. Run deployment again: python3 deploy.py user@raspberry-pi-ip
3. Log out and back in to see changes

↩️ Reverting the Changes

A revert script is provided to cleanly uninstall the bootstrap environment and return your Pi to its default bash shell.

The script will:

• Change your default shell back to bash.
• Restore your original shell configuration from a backup if one was made.
• Interactively ask for confirmation before removing packages and directories.

To run the revert script:

python3 revert.py user@raspberry-pi-ip

After the script finishes, log out and log back in to your Pi to return to your bash session.

📝 Notes

• Your original .zshrc is backed up to ~/.zshrc.backup.[timestamp]
• The setup script is idempotent - safe to run multiple times
• All plugins are kept in ~/repos/ for easy management
• Znap automatically manages plugin updates with znap pull

🐛 Known Issues

None at this time. If you encounter issues, check that:

• Your Pi is running a recent version of Raspberry Pi OS
• You have sudo access on the Pi
• Network connectivity is stable during deployment

📜 License

MIT License - Feel free to use and modify as needed.

🙏 Acknowledgments

• Znap by @marlonrichert
• Powerlevel10k by @romkatv
• Oh My Zsh community
• All the Zsh plugin authors