Welcome to SwitchShuttle
Relevant source files
The following files were used as context for generating this wiki page:
SwitchShuttle is a cross-platform system tray application designed to manage and execute terminal commands through a streamlined graphical interface and global hotkeys. Built using the Tauri framework with a Rust backend and a Vue.js frontend, it allows developers and power users to organize complex command-line workflows into accessible menus. Sources: README.md:16-18, package.json:2-4
The application serves as a command hub, supporting multiple terminal emulators like iTerm2, Warp, and Alacritty. It provides features such as dynamic input prompts, scheduled tasks via cron, and background execution, all while maintaining system safety through an integrated security manager that validates commands against malicious patterns. Sources: README.md:21-36, src/pages/About.vue:68-71
System Architecture
SwitchShuttle utilizes a multi-layered architecture where the frontend (Vue.js) handles user interactions and configuration editing, while the backend (Rust/Tauri) manages system-level operations, terminal spawning, and tray menu integration. Sources: README.md:18, src-tauri/tauri.conf.json:3-7
Application Flow
The following diagram illustrates how a user interaction in the system tray triggers a command execution within a target terminal.
The application flow demonstrates the centralized role of the Tauri backend in validating and routing commands from various entry points (Tray, Hotkeys, CLI). Sources: README.md:143-155, src/lib/security.ts:133-140
Core Features and Components
SwitchShuttle is organized into several functional modules that manage the lifecycle of a command from configuration to execution. Sources: README.md:41-65
| Feature | Description | Relevant File |
|---|---|---|
| Configuration Editor | A visual JSON editor for managing command sets. | README.md:44 |
| Command Builder | Interface for defining names, icons, and hotkeys. | README.md:54 |
| Security Manager | Validates commands against blocked patterns and lengths. | src/lib/security.ts:47 |
| Template System | Pre-defined command sets for DevOps, DB, and Security. | README.md:104-114 |
| Tray Integration | Provides quick access to commands via the OS system tray. | src-tauri/tauri.conf.json:151-155 |
Command Types
SwitchShuttle supports various execution patterns to cater to different operational needs:
- Basic Commands: Simple terminal executions. Sources: src/pages/Help.vue:152
- Switch Commands: Toggleable features that detect current status (e.g., WiFi toggle). Sources: README.md:281-295
- Monitor Commands: Commands that display real-time output (CPU/Memory) directly in the menu. Sources: README.md:308-323
- Scheduled Commands: Automation using standard 6-field cron expressions. Sources: README.md:248-255
Security Implementation
The SecurityManager is a critical system component that protects the host machine from dangerous operations. It implements singleton logic to provide consistent validation across the frontend editor and the execution engine. Sources: src/lib/security.ts:47-111
Validation Logic
Before any command is saved or executed, it undergoes a series of checks:
- Length Validation: Ensures commands do not exceed 1000 characters and inputs stay under 500 characters. Sources: src/lib/security.ts:50-54
- Pattern Matching: Uses RegEx to identify suspicious strings like
rm -rf,sudo,chmod 777, orpowerhsell. Sources: src/lib/security.ts:55-80 - Command Splitting: Analyzes sub-commands separated by
&&,||, or;to ensure nested logic is safe. Sources: src/lib/security.ts:145-150
The sequence diagram shows the mandatory validation gate during the command creation process. Sources: src/lib/security.ts:133-210
Configuration and Environment
SwitchShuttle stores its settings in platform-specific directories, ensuring a native feel across operating systems. Sources: README.md:188-191, src/pages/Help.vue:103-113
Storage Locations
- macOS/Linux:
~/.config/switch-shuttle/ - Windows:
C:\Users\<Username>\AppData\Roaming\switch-shuttle\
Terminal Support matrix
The application interacts with various terminal emulators depending on the host OS. Sources: README.md:342-348, src/pages/About.vue:62-65
| Terminal | macOS | Windows | Linux |
|---|---|---|---|
| iTerm2 | ✅ | ❌ | ❌ |
| Terminal.app | ✅ | ❌ | ❌ |
| Warp | ✅ | ❌ | ❌ |
| Alacritty | ✅ | ✅ | ✅ |
| PowerShell | ❌ | ✅ | ❌ |
| GNOME Terminal | ❌ | ❌ | ✅ |
Development and Extensibility
The project is managed via pnpm and relies on Tauri plugins for core OS features like autostart, global shortcuts, and shell execution. Sources: package.json:42-55
Key Dependencies
- @tauri-apps/api: Facilitates communication between the Vue frontend and Rust backend.
- @tauri-apps/plugin-shell: Used to spawn terminal windows and execute commands.
- @tauri-apps/plugin-global-shortcut: Registers system-wide keybindings.
- vue-router: Manages navigation between the Editor, Settings, and Help pages.
Sources: package.json:42-60
Build Scripts
Developers can use the following scripts for project maintenance:
pnpm run tauri dev: Starts the application in development mode with hot-reloading.pnpm run build: Compiles the Vue frontend and checks types.pnpm run tauri build: Packages the application for production.
Sources: package.json:11-15
SwitchShuttle provides a robust framework for terminal command automation, combining ease of use via its GUI with the power of the command line. Its emphasis on security and cross-platform compatibility makes it a versatile tool for various technical workflows. Sources: README.md:434-436