Extension Icon

Zshrc Manager

View and manage your ~/.zshrc from Raycast
AvatarEitel Dagnin
1,363 Installs
Overview

Zshrc Manager Icon

Zshrc Manager

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.

FeaturesCommandsUsageConfigurationDevelopmentContributing


✨ Features

🏠Unified HomeOne search-first surface: recents, tools with a live health badge, category counts, and discovery — typing searches your whole config at once
🖥️Alias ManagementBrowse, add, edit, and search aliases organized by sections with full validation
📦Export ManagementManage environment variable exports with search by variable name or value
⚙️Advanced ConfigView and manage functions, plugins, sources, evals, setopts, PATH entries, and keybindings
🔍Smart SearchSearch across all content types with real-time filtering by section, name, command, or value
📝Section ManagementView zshrc content organized by logical sections with detailed breakdowns
💾Backup & RestoreAutomatic backups before edits with one-click restore functionality
↩️Undo HistorySession-based undo/redo for all edit operations

🚀 One Command, Every Surface

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.

SurfaceWhat it holdsReach it by
🕘 Recently ManagedEvery entry you've touched here, ranked by frecencyBrowse, at rest
🏥 Health CheckDuplicates, conflicts and broken sources, with a live issue badgeTools row or ⌘⇧H
💾 Backup ManagerRestore or diff a previous versionTools row or ⌘⇧B
↩️ HistoryUndo and redo recent changesTools row or ⌘⇧Y
📁 BrowseSections, Aliases, Exports, Functions, Plugins, Sources, Evals, Setopts, PATH, FPATH, Keybindings — each with a count, each a focused view on a category
📚 DiscoverCurated alias collections you can addDiscover row, ⌘⇧L, or inline under "Available to Add" while searching

📖 Usage

Getting Started

  1. Install the extension from the Raycast Store
  2. Open Zshrc Manager — the home surface shows your whole configuration at a glance
  3. Type to search across every entry type (and the catalogue) at once
  4. Use actions to add, edit, or copy content; ⌘⇧D toggles the detail pane
📝 Adding New Aliases
  1. Open Aliases from the home Browse section
  2. Press Cmd+N or click "Add New Alias"
  3. Enter the alias name and command
  4. Select or create a section
  5. Save to add to your zshrc file
# Example: Add a quick git status alias
alias gs='git status'
📦 Managing Exports
  1. Open Exports from the home Browse section
  2. Press Cmd+N to add a new export
  3. Enter the variable name (uppercase recommended) and value
  4. Save to update your zshrc file
# Example: Set your default editor
export EDITOR=code
🔍 Searching Content
  • Use the search bar in any command
  • Search by name, command, section, or value
  • Results update in real-time as you type
  • The landing view searches across all entry types at once — and every result can be edited, deleted, or copied in place

⚙️ Configuration

Built-in Section Formats

The extension automatically detects sections using these patterns:

FormatExampleDescription
Labeled# Section: NameSimple labeled sections
Dashed# --- Name --- #Dashed delimiter sections
Bracketed# [Name]Bracketed sections
Hash## NameDouble-hash sections
Tags# @start Name / # @end NameCustom start/end tags
FunctionsmyFunc() { ... }Function definitions
🔧 Custom Section Patterns

Configure custom patterns in Raycast Preferences:

  1. Open Raycast Preferences
  2. Go to Extensions → Zshrc Manager
  3. Configure your custom patterns

Custom Header Pattern

  • Enable Custom Header Pattern: Toggle to enable
  • Custom Header Pattern: Regex with one capture group for section name
# Example: Match "# My Section"
^#\s+(.+)$

Custom Start/End Patterns

  • Enable Custom Start/End Patterns: Toggle to enable
  • Custom Start Pattern: Regex with one capture group
  • Custom End Pattern: Regex for end markers
# Start pattern
^#\s*start\s+(.+)$

# End pattern
^#\s*end\s+(.+)$

Pattern Requirements

  • Patterns must include exactly one capture group (...) for the section name
  • Patterns are automatically anchored to the start of the line (^)
  • Matching is case-insensitive
  • Invalid patterns are ignored, falling back to defaults

⌨️ Keyboard Shortcuts

ShortcutAction
Cmd+NAdd new alias/export
Cmd+RRefresh data
Cmd+OOpen ~/.zshrc in default editor
Cmd+CCopy selected content
Cmd+ZUndo last change
Cmd+Shift+ZRedo

📋 Requirements

RequirementDetails
🐚 ShellZsh (Z shell)
📄 File~/.zshrc configuration file
🔐 PermissionsRead/write access to home directory

🛡️ Error Handling

ScenarioBehavior
📁 File Not FoundGraceful fallback with cached data
🔒 Permission ErrorsClear error messages with suggestions
📏 Large FilesAutomatic content truncation (1MB limit)
✅ ValidationInput validation for aliases and exports
💾 BackupsAutomatic .zshrc.bak before writes

🔧 Development

# 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
📁 Project Structure
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)

🤝 Contributing

We welcome contributions!

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Ensure all tests pass
  6. Submit a pull request

📄 License

MIT License


🔗 Links

ResourceLink
🐛 IssuesGitHub Issues
📚 DocumentationRaycast Developer Docs
📝 ChangelogCHANGELOG.md
⚠️ LimitationsLIMITATIONS.md

Made with ❤️ for the Raycast community