{"id":31306146,"url":"https://github.com/thgossler/menv","last_synced_at":"2026-05-18T02:10:52.137Z","repository":{"id":315683082,"uuid":"1060475118","full_name":"thgossler/menv","owner":"thgossler","description":"A CLI tool to manage user environment variables on macOS for both GUI and terminal apps.","archived":false,"fork":false,"pushed_at":"2025-09-20T02:05:43.000Z","size":28,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-20T04:10:16.738Z","etag":null,"topics":["environment-variables","gui","macos","shell-script","terminal"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thgossler.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-20T01:41:10.000Z","updated_at":"2025-09-20T02:05:47.000Z","dependencies_parsed_at":"2025-09-20T04:10:18.354Z","dependency_job_id":"567cb6ce-968b-4014-9725-62e6163cfc32","html_url":"https://github.com/thgossler/menv","commit_stats":null,"previous_names":["thgossler/menv"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/thgossler/menv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thgossler%2Fmenv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thgossler%2Fmenv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thgossler%2Fmenv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thgossler%2Fmenv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thgossler","download_url":"https://codeload.github.com/thgossler/menv/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thgossler%2Fmenv/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33162448,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-17T22:39:12.733Z","status":"online","status_checked_at":"2026-05-18T02:00:06.436Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["environment-variables","gui","macos","shell-script","terminal"],"created_at":"2025-09-25T04:13:39.400Z","updated_at":"2026-05-18T02:10:52.108Z","avatar_url":"https://github.com/thgossler.png","language":"Shell","funding_links":["https://www.paypal.com/donate/?hosted_button_id=JVG7PFJ8DMW7J","https://github.com/sponsors/thgossler"],"categories":[],"sub_categories":[],"readme":"\u003c!-- PROJECT LOGO --\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003emenv\u003c/h1\u003e\n  \u003cp align=\"center\"\u003eA command line tool to manage environment variables on macOS\u003c/p\u003e\n\u003c/div\u003e\n\n\u003c!-- SHIELDS --\u003e\n\u003cdiv align=\"center\"\u003e\n\n[![Contributors][contributors-shield]][contributors-url]\n[![Forks][forks-shield]][forks-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Issues][issues-shield]][issues-url]\n[![MIT License][license-shield]][license-url]\n\n\u003c/div\u003e\n\n## 🚀 Overview\n\n`menv` simplifies user-scope environment variable management on macOS by handling the complexity of making variables available to both GUI applications and terminal sessions across different contexts:\n\n- **GUI Applications** (VS Code, browsers, etc.) via `launchctl`\n- **Terminal Sessions** (bash, zsh, fish) via shell profiles\n- **Persistent across reboots** via LaunchAgent plists and profile files\n\n## 📋 Table of Contents\n\n- [Installation](#-installation)\n- [Quick Start](#-quick-start)\n- [Commands](#-commands)\n- [PATH-like Variables](#-path-like-variables)\n- [Sources Managed](#-sources-managed)\n- [Examples](#-examples)\n- [Advanced Usage](#-advanced-usage)\n- [Troubleshooting](#-troubleshooting)\n\n## 🛠 Installation\n\n1. **Download the script:**\n   ```bash\n   curl -O https://raw.githubusercontent.com/thgossler/menv/refs/heads/main/menv.sh\n   chmod +x menv.sh\n   ```\n\n2. **Make it globally available (optional):**\n   ```bash\n   sudo cp menv.sh /usr/local/bin/menv\n   ```\n\n3. **Verify installation:**\n   ```bash\n   ./menv.sh --help\n   # or if installed globally:\n   menv --help\n   ```\n\n## ⚡ Quick Start\n\n```bash\n# List all environment variables\nmenv list\n\n# Add a new environment variable\nmenv add MY_API_KEY \"abc123def456\"\n\n# Add Java home\nmenv set JAVA_HOME \"/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home\"\n\n# Add a directory to PATH\nmenv add-path PATH \"/usr/local/custom/bin\"\n\n# View detailed information about a variable\nmenv info PATH\n\n# Remove a variable\nmenv delete OLD_VARIABLE\n```\n\n## 📖 Commands\n\n### `list` - List Environment Variables\n\nShows all environment variables in a clean table format.\n\n```bash\n# List all variables\nmenv list\n\n# Example output:\n# NAME                    VALUE                                           SOURCES\n# ----------------------- ----------------------------------------------- -----------\n# HOME                    /Users/john                                     inherited\n# PATH                    /usr/local/bin:/usr/bin:/bin                    launchctl\n# MY_API_KEY              abc123def456                                    launchctl, shell-profile\n```\n\n### `add` / `set` - Add or Set Variables\n\nCreates or updates an environment variable. Both commands work identically.\n\n```bash\n# Basic usage\nmenv add VARIABLE_NAME \"value\"\nmenv set VARIABLE_NAME \"value\"\n\n# Examples\nmenv add API_KEY \"your-secret-key\"\nmenv set EDITOR \"code\"\nmenv add JAVA_OPTS \"-Xmx2g -Xms1g\"\n```\n\n**For PATH-like variables**, you'll be prompted with options:\n```bash\nmenv add PATH \"/new/directory\"\n# Prompts:\n# 1) Append to existing PATH (recommended)\n# 2) Prepend to existing PATH  \n# 3) Replace entire PATH (dangerous!)\n```\n\n### `delete` / `del` / `remove` - Remove Variables\n\nRemoves a variable from all locations where it's defined.\n\n```bash\n# Remove a variable\nmenv delete VARIABLE_NAME\n\n# Force removal without confirmation\nmenv --force delete VARIABLE_NAME\n\n# Examples\nmenv delete OLD_API_KEY\nmenv delete DEPRECATED_VAR\n```\n\n### `add-path` - Add PATH Entries\n\nSafely adds directories to PATH-like variables without prompting.\n\n```bash\n# Add to PATH (appends by default)\nmenv add-path PATH \"/usr/local/custom/bin\"\n\n# Add to other PATH-like variables\nmenv add-path LIBRARY_PATH \"/usr/local/lib\"\nmenv add-path PYTHONPATH \"/usr/local/python/modules\"\n```\n\n### `remove-path` - Remove PATH Entries\n\nRemoves specific directories from PATH-like variables.\n\n```bash\n# Remove from PATH\nmenv remove-path PATH \"/old/directory\"\n\n# Remove from other PATH-like variables  \nmenv remove-path LIBRARY_PATH \"/deprecated/lib\"\n```\n\n### `info` - Variable Information\n\nShows detailed information about a specific variable.\n\n```bash\n# Get detailed info\nmenv info VARIABLE_NAME\n\n# Example output for PATH:\n# Current environment: /usr/local/bin:/usr/bin:/bin\n# \n# Launchctl status:\n#   ✓ launchctl: /usr/local/bin:/usr/bin:/bin\n# \n# Shell profile status:\n#   ✗ Not found in configuration files\n# \n# Fresh shell test:\n#   ✓ Fresh shell would see: /usr/local/bin:/usr/bin:/bin\n```\n\n### `test` - Test Variables\n\nVerifies that a variable works in fresh shell and GUI environments.\n\n```bash\n# Test a variable\nmenv test MY_API_KEY\n\n# Example output:\n# ✓ Variable 'MY_API_KEY' is set to: abc123def456\n# ✓ Variable 'MY_API_KEY' is set in launchctl: abc123def456\n```\n\n### `analyze` - Analyze PATH Variables\n\nAnalyzes PATH-like variables for duplicates, missing directories, and composition.\n\n```bash\n# Analyze PATH\nmenv analyze PATH\n\n# Example output shows:\n# - All PATH entries with existence status\n# - Duplicate detection\n# - Source analysis\n# - Recommendations for cleanup\n```\n\n## 🛤 PATH-like Variables\n\nThe following variables receive special treatment for path management:\n\n- `PATH`\n- `LIBRARY_PATH`\n- `LD_LIBRARY_PATH`\n- `DYLD_LIBRARY_PATH`\n- `PKG_CONFIG_PATH`\n- `MANPATH`\n- `INFOPATH`\n- `CLASSPATH`\n- `PYTHONPATH`\n- `NODE_PATH`\n\n### Special Behavior\n\n- **`add` command**: Prompts for append/prepend/replace options\n- **`add-path` command**: Always appends safely\n- **`remove-path` command**: Removes specific entries\n- **`delete` command**: Warns about removing entire variable\n- **`analyze` command**: Shows composition and duplicates\n\n## 📁 Sources Managed\n\n`menv` manages environment variables across multiple sources:\n\n| Source | Description | Purpose |\n|--------|-------------|---------|\n| **`launchctl`** | User launchctl environment | GUI applications |\n| **`shell-profile`** | Shell profile files | Terminal sessions |\n| **`user-plist`** | LaunchAgent plist files | Persistence across reboots |\n| **`macos-environment-plist`** | Legacy environment.plist | Backwards compatibility |\n| **`inherited`** | System/parent process variables | Context only (read-only) |\n\n### Shell Profiles Supported\n\n- `~/.zshrc` (Zsh)\n- `~/.bash_profile` (Bash)\n- `~/.bashrc` (Bash)\n- `~/.profile` (Generic)\n- `~/.zshenv` (Zsh)\n- `~/.bash_login` (Bash)\n- `~/.zprofile` (Zsh)\n- `~/.config/fish/config.fish` (Fish shell)\n\n## 💡 Examples\n\n### Development Environment Setup\n\n```bash\n# Set up Node.js development\nmenv add NODE_ENV \"development\"\nmenv add-path PATH \"$HOME/.npm-global/bin\"\nmenv add-path NODE_PATH \"$HOME/.npm-global/lib/node_modules\"\n\n# Set up Python development\nmenv add PYTHONPATH \"$HOME/python/modules\"\nmenv add-path PATH \"$HOME/.local/bin\"\n\n# Set up Java development\nmenv set JAVA_HOME \"/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home\"\nmenv add-path PATH \"$JAVA_HOME/bin\"\n```\n\n### API Keys and Secrets\n\n```bash\n# Add API keys (be careful with sensitive data!)\nmenv add OPENAI_API_KEY \"your-api-key-here\"\nmenv add GITHUB_TOKEN \"your-github-token\"\nmenv add DATABASE_URL \"postgresql://user:pass@localhost/db\"\n\n# Set default applications\nmenv set EDITOR \"code\"\nmenv set BROWSER \"firefox\"\n```\n\n### Custom Tool Paths\n\n```bash\n# Add Homebrew paths\nmenv add-path PATH \"/opt/homebrew/bin\"\nmenv add-path PATH \"/opt/homebrew/sbin\"\n\n# Add custom binary directories\nmenv add-path PATH \"$HOME/bin\"\nmenv add-path PATH \"$HOME/.local/bin\"\nmenv add-path PATH \"/usr/local/custom/bin\"\n```\n\n### Managing Existing Variables\n\n```bash\n# Check what's currently set\nmenv list | grep API\n\n# Get detailed information\nmenv info PATH\nmenv info JAVA_HOME\n\n# Analyze PATH for problems\nmenv analyze PATH\n\n# Clean up old variables\nmenv delete OLD_API_KEY\nmenv delete DEPRECATED_PATH\n```\n\n### Batch Operations\n\n```bash\n# Set multiple related variables\nmenv add AWS_REGION \"us-west-2\"\nmenv add AWS_DEFAULT_REGION \"us-west-2\"\nmenv add AWS_OUTPUT \"json\"\n\n# Remove multiple old variables\nmenv --force delete OLD_VAR_1\nmenv --force delete OLD_VAR_2\nmenv --force delete OLD_VAR_3\n```\n\n## 🔧 Advanced Usage\n\n### Options\n\n- **`-f, --force`**: Skip confirmation prompts\n- **`-v, --verbose`**: Enable debug output\n- **`-h, --help`**: Show help message\n\n### Verbose Mode\n\n```bash\n# See what the tool is doing internally\nmenv --verbose add MY_VAR \"value\"\nmenv --verbose list\n```\n\n### Force Mode\n\n```bash\n# Skip all confirmation prompts\nmenv --force delete RISKY_VARIABLE\nmenv --force add PATH \"/risky/path\"\n```\n\n### PATH Management Strategies\n\n```bash\n# Safe PATH addition (recommended)\nmenv add-path PATH \"/new/directory\"\n\n# Interactive PATH modification with choices\nmenv add PATH \"/new/directory\"\n\n# Analyze before modifying\nmenv analyze PATH\nmenv add-path PATH \"/optimized/path\"\nmenv analyze PATH  # Check the result\n```\n\n## 🩺 Troubleshooting\n\n### Variable Not Available in GUI Apps\n\n```bash\n# Check if it's set in launchctl\nmenv info MY_VARIABLE\n\n# If not in launchctl, add it properly\nmenv add MY_VARIABLE \"value\"\n\n# Restart GUI applications to pick up changes\n```\n\n### Variable Not Available in Terminal\n\n```bash\n# Check shell profile status\nmenv info MY_VARIABLE\n\n# Open a new terminal session\n# or source your profile manually:\nsource ~/.zshrc  # or your shell's profile\n```\n\n### PATH Issues\n\n```bash\n# Analyze PATH for problems\nmenv analyze PATH\n\n# Common issues and solutions:\n# - Duplicates: Remove and re-add paths\n# - Missing directories: Remove non-existent paths  \n# - Wrong order: Use prepend instead of append\n\n# Fix duplicate homebrew paths\nmenv remove-path PATH \"/opt/homebrew/bin\"  # remove duplicate\nmenv add-path PATH \"/opt/homebrew/bin\"     # add once\n```\n\n### Backup and Restore\n\nThe tool automatically creates backups before modifying files:\n\n```bash\n# Backups are created in the same directory with timestamp\n# Example: ~/.zshrc.backup.20240920_143022\n\n# To restore a backup:\ncp ~/.zshrc.backup.20240920_143022 ~/.zshrc\n```\n\n### Common Error Messages\n\n**\"Variable name cannot be empty\"**\n```bash\n# Fix: Provide a variable name\nmenv add \"\" \"value\"          # ❌ Wrong\nmenv add MY_VARIABLE \"value\" # ✅ Correct\n```\n\n**\"Administrator privileges required\"**\n```bash\n# This shouldn't happen with user-scope operations\n# If you see this, there might be a bug - please report it\n```\n\n**\"Variable not found\"**\n```bash\n# The variable doesn't exist in managed locations\nmenv info NON_EXISTENT_VAR\n# Check if it's inherited:\nmenv list | grep NON_EXISTENT_VAR\n```\n\n## 📝 Notes\n\n- **GUI Applications**: Need to be restarted to see new environment variables\n- **Terminal Sessions**: Need to be reopened or profiles re-sourced\n- **Persistence**: Variables are automatically persistent across reboots\n- **Safety**: Only manages user-scope variables, never requires sudo\n- **Backups**: Automatically creates backups before modifying files\n\n## 💰​ Donate\n\nIf you are using the tool but are unable to contribute technically, please consider promoting it and donating an amount that reflects its value to you. You can do so either via PayPal\n\n[![Donate via PayPal](https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif)](https://www.paypal.com/donate/?hosted_button_id=JVG7PFJ8DMW7J)\n\nor via [GitHub Sponsors](https://github.com/sponsors/thgossler).\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b my-feature`\n3. Make your changes\n4. Test thoroughly on macOS\n5. Submit a pull request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙋 Support\n\nIf you encounter issues:\n\n1. Check the troubleshooting section above\n2. Run with `--verbose` to see detailed output\n3. Check that you're on a supported macOS version\n4. Open an issue with detailed information about your environment\n\n\n\u003c!-- MARKDOWN LINKS \u0026 IMAGES (https://www.markdownguide.org/basic-syntax/#reference-style-links) --\u003e\n[contributors-shield]: https://img.shields.io/github/contributors/thgossler/menv.svg\n[contributors-url]: https://github.com/thgossler/menv/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/thgossler/menv.svg\n[forks-url]: https://github.com/thgossler/menv/network/members\n[stars-shield]: https://img.shields.io/github/stars/thgossler/menv.svg\n[stars-url]: https://github.com/thgossler/menv/stargazers\n[issues-shield]: https://img.shields.io/github/issues/thgossler/menv.svg\n[issues-url]: https://github.com/thgossler/menv/issues\n[license-shield]: https://img.shields.io/github/license/thgossler/menv.svg\n[license-url]: https://github.com/thgossler/menv/blob/main/LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthgossler%2Fmenv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthgossler%2Fmenv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthgossler%2Fmenv/lists"}