A powerful Raycast extension for managing your ~/.zshrc configuration file
View, organize, and edit your shell aliases, exports, functions, and more with an intuitive interface.
Features • Commands • Usage • Configuration • Development • Contributing
| 🏠 | Unified Home | One search-first surface: recents, tools with a live health badge, category counts, and discovery — typing searches your whole config at once |
| 🖥️ | Alias Management | Browse, add, edit, and search aliases organized by sections with full validation |
| 📦 | Export Management | Manage environment variable exports with search by variable name or value |
| ⚙️ | Advanced Config | View and manage functions, plugins, sources, evals, setopts, PATH entries, and keybindings |
| 🔍 | Smart Search | Search across all content types with real-time filtering by section, name, command, or value |
| 📝 | Section Management | View zshrc content organized by logical sections with detailed breakdowns |
| 💾 | Backup & Restore | Automatic backups before edits with one-click restore functionality |
| ↩️ | Undo History | Session-based undo/redo for all edit operations |
The Zshrc Manager command opens a single home surface. At rest it shows an overview; press ⏎ on a category to drill into a focused view (Esc returns home), or just start typing to search everything at once.
| Surface | What it holds | Reach it by |
|---|---|---|
| 🕘 Recently Managed | Every entry you've touched here, ranked by frecency | Browse, at rest |
| 🏥 Health Check | Duplicates, conflicts and broken sources, with a live issue badge | Tools row or ⌘⇧H |
| 💾 Backup Manager | Restore or diff a previous version | Tools row or ⌘⇧B |
| ↩️ History | Undo and redo recent changes | Tools row or ⌘⇧Y |
| 📁 Browse | Sections, Aliases, Exports, Functions, Plugins, Sources, Evals, Setopts, PATH, FPATH, Keybindings — each with a count, each a focused view | ⏎ on a category |
| 📚 Discover | Curated alias collections you can add | Discover row, ⌘⇧L, or inline under "Available to Add" while searching |
⌘⇧D toggles the detail paneCmd+N or click "Add New Alias"# Example: Add a quick git status alias
alias gs='git status'
Cmd+N to add a new export# Example: Set your default editor
export EDITOR=code
The extension automatically detects sections using these patterns:
| Format | Example | Description |
|---|---|---|
| Labeled | # Section: Name | Simple labeled sections |
| Dashed | # --- Name --- # | Dashed delimiter sections |
| Bracketed | # [Name] | Bracketed sections |
| Hash | ## Name | Double-hash sections |
| Tags | # @start Name / # @end Name | Custom start/end tags |
| Functions | myFunc() { ... } | Function definitions |
Configure custom patterns in Raycast Preferences:
# Example: Match "# My Section"
^#\s+(.+)$
# Start pattern
^#\s*start\s+(.+)$
# End pattern
^#\s*end\s+(.+)$
(...) for the section name^)| Shortcut | Action |
|---|---|
Cmd+N | Add new alias/export |
Cmd+R | Refresh data |
Cmd+O | Open ~/.zshrc in default editor |
Cmd+C | Copy selected content |
Cmd+Z | Undo last change |
Cmd+Shift+Z | Redo |
| Requirement | Details |
|---|---|
| 🐚 Shell | Zsh (Z shell) |
| 📄 File | ~/.zshrc configuration file |
| 🔐 Permissions | Read/write access to home directory |
| Scenario | Behavior |
|---|---|
| 📁 File Not Found | Graceful fallback with cached data |
| 🔒 Permission Errors | Clear error messages with suggestions |
| 📏 Large Files | Automatic content truncation (1MB limit) |
| ✅ Validation | Input validation for aliases and exports |
| 💾 Backups | Automatic .zshrc.bak before writes |
# Install dependencies
npm install
# Development mode
npm run dev
# Build
npm run build
# Testing
npm run test
npm run test:coverage
# Linting
npm run lint
npm run fix-lint
src/
├── __tests__/ # Test files (mirror src structure)
├── components/ # Reusable UI components
├── data/ # Static data (templates)
├── hooks/ # React hooks for state management
├── lib/ # Core business logic
├── types/ # TypeScript type definitions
├── utils/ # Pure utility functions
└── *.tsx # UI components (commands)
We welcome contributions!
MIT License
| Resource | Link |
|---|---|
| 🐛 Issues | GitHub Issues |
| 📚 Documentation | Raycast Developer Docs |
| 📝 Changelog | CHANGELOG.md |
| ⚠️ Limitations | LIMITATIONS.md |
Made with ❤️ for the Raycast community