| Name | brewfile JSON |
| Version |
0.1.3
JSON |
| download |
| home_page | None |
| Summary | Intelligent Homebrew package management using brew bundle with JSON configuration and machine-aware installations |
| upload_time | 2025-09-09 01:30:59 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
homebrew
brew
package-management
macos
cli
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Brewfile - Intelligent Homebrew Package Management
Brewfile is a command-line tool that provides intelligent Homebrew package management using `brew bundle` with JSON configuration and machine-aware installations.
## Features
- **Machine-aware configurations**: Different package sets for different machines
- **Package groups**: Organize packages into logical groups (e.g., "development", "media", "work")
- **Intelligent sync operations**: Install missing packages, remove extras, or adopt system packages
- **Interactive workflows**: Safe operations with confirmations
- **Full Homebrew support**: Formulas, casks, taps, and Mac App Store apps
- **Type-safe operations**: Automatic package type detection with manual overrides
- **Status reporting**: Clear visibility into what's installed, missing, or extra
## Installation
### From PyPI (Recommended)
```bash
pip install brewfile
```
### From Source
```bash
git clone https://github.com/waltermwaniki/brewfile.git
cd brewfile
uv sync
uv run brewfile --help
```
## Quick Start
1. **Initialize configuration:**
```bash
brewfile init
```
2. **Check current status:**
```bash
brewfile status
```
3. **Add packages:**
```bash
brewfile add neovim
brewfile add --cask visual-studio-code
```
4. **Sync your system:**
```bash
brewfile sync-adopt # Safe: installs missing, adopts extras
brewfile sync-cleanup # Removes extra packages (destructive)
```
## Configuration
Brewfile uses a JSON configuration file at `~/.config/brewfile.json`:
```json
{
"version": "1.0",
"packages": {
"development": {
"taps": ["homebrew/cask-fonts"],
"brews": ["git", "neovim", "python"],
"casks": ["visual-studio-code", "docker"],
"mas": ["Xcode::497799835"]
},
"media": {
"brews": ["ffmpeg", "youtube-dl"],
"casks": ["vlc", "spotify"]
}
},
"machines": {
"work-laptop": ["development"],
"personal-mac": ["development", "media"]
}
}
```
## Commands
### Core Commands
- `brewfile init` - Initialize configuration with current system packages
- `brewfile status` - Show package status and synchronization state
- `brewfile add <package>` - Add package to configuration and install
- `brewfile remove <package>` - Remove package from system and configuration
- `brewfile edit` - Open configuration file in editor
### Sync Commands
- `brewfile sync-adopt` - Install missing packages + adopt extra packages to config (safe)
- `brewfile sync-cleanup` - Install missing packages + remove extra packages (destructive)
### Interactive Mode
Run `brewfile` without arguments to enter interactive mode with guided workflows.
## Advanced Usage
### Package Types
Brewfile automatically detects package types, but you can force specific types:
```bash
brewfile add --cask chrome # Force as cask
brewfile add neovim # Auto-detect (formula)
```
### Machine-Specific Configurations
Configure different package sets for different machines by hostname:
```json
{
"machines": {
"work-macbook": ["development", "work-tools"],
"personal-imac": ["development", "gaming", "media"]
}
}
```
### Mac App Store Apps
Include Mac App Store apps with app IDs:
```bash
brewfile add "Xcode::497799835" # Format: AppName::AppID
```
## Configuration Management
### Package Groups
Organize packages into logical groups:
- **development**: Development tools and languages
- **media**: Audio/video tools and entertainment
- **work**: Work-specific applications
- **gaming**: Games and gaming tools
### Dotfiles Integration
**Brewfile works exceptionally well with dotfiles management systems!** 🔗
For multi-machine synchronization:
1. **Store your config in dotfiles**: Add `~/.config/brewfile.json` to your dotfiles repository
2. **Symlink on new machines**: Your dotfiles manager can symlink the config automatically
3. **Machine-aware setup**: Different machines automatically get their appropriate package groups
4. **One command setup**: Run `brewfile sync-adopt` on a new machine to get all your tools
```bash
# Example dotfiles setup
# In your dotfiles repo:
~/dotfiles/config/brewfile.json -> ~/.config/brewfile.json
# On a new machine after dotfiles setup:
brewfile sync-adopt # Installs all packages for this machine
```
This approach ensures consistent development environments across all your machines while respecting machine-specific needs (e.g., work laptop vs. personal desktop).
### Best Practices
1. Keep packages in appropriate groups
2. Use machine-specific configurations for different setups
3. Store your brewfile config in your dotfiles repository
4. Regularly run `brewfile status` to maintain sync
5. Use `sync-adopt` for safe operations, `sync-cleanup` when you need to clean up
## Requirements
- macOS (Homebrew is macOS-specific)
- Python 3.9 or higher
- Homebrew installed
- Optional: `mas` for Mac App Store apps
## License
MIT License - see LICENSE file for details.
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## Support
If you encounter issues or have questions:
1. Check existing [GitHub Issues](https://github.com/waltermwaniki/brewfile/issues)
2. Create a new issue with details about your problem
3. Include your configuration file (with sensitive data removed)
---
**Happy brewing! 🍺**
Raw data
{
"_id": null,
"home_page": null,
"name": "brewfile",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "homebrew, brew, package-management, macos, cli",
"author": null,
"author_email": "Walter Mwaniki <walter.g.mwaniki@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f7/39/60d7d0e5bf5ea0f379d633465d0d1344d0e8b906134a540aaa60d3f45d4d/brewfile-0.1.3.tar.gz",
"platform": null,
"description": "# Brewfile - Intelligent Homebrew Package Management\n\nBrewfile is a command-line tool that provides intelligent Homebrew package management using `brew bundle` with JSON configuration and machine-aware installations.\n\n## Features\n\n- **Machine-aware configurations**: Different package sets for different machines\n- **Package groups**: Organize packages into logical groups (e.g., \"development\", \"media\", \"work\")\n- **Intelligent sync operations**: Install missing packages, remove extras, or adopt system packages\n- **Interactive workflows**: Safe operations with confirmations\n- **Full Homebrew support**: Formulas, casks, taps, and Mac App Store apps\n- **Type-safe operations**: Automatic package type detection with manual overrides\n- **Status reporting**: Clear visibility into what's installed, missing, or extra\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install brewfile\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/waltermwaniki/brewfile.git\ncd brewfile\nuv sync\nuv run brewfile --help\n```\n\n## Quick Start\n\n1. **Initialize configuration:**\n\n ```bash\n brewfile init\n ```\n\n2. **Check current status:**\n\n ```bash\n brewfile status\n ```\n\n3. **Add packages:**\n\n ```bash\n brewfile add neovim\n brewfile add --cask visual-studio-code\n ```\n\n4. **Sync your system:**\n\n ```bash\n brewfile sync-adopt # Safe: installs missing, adopts extras\n brewfile sync-cleanup # Removes extra packages (destructive)\n ```\n\n## Configuration\n\nBrewfile uses a JSON configuration file at `~/.config/brewfile.json`:\n\n```json\n{\n \"version\": \"1.0\",\n \"packages\": {\n \"development\": {\n \"taps\": [\"homebrew/cask-fonts\"],\n \"brews\": [\"git\", \"neovim\", \"python\"],\n \"casks\": [\"visual-studio-code\", \"docker\"],\n \"mas\": [\"Xcode::497799835\"]\n },\n \"media\": {\n \"brews\": [\"ffmpeg\", \"youtube-dl\"],\n \"casks\": [\"vlc\", \"spotify\"]\n }\n },\n \"machines\": {\n \"work-laptop\": [\"development\"],\n \"personal-mac\": [\"development\", \"media\"]\n }\n}\n```\n\n## Commands\n\n### Core Commands\n\n- `brewfile init` - Initialize configuration with current system packages\n- `brewfile status` - Show package status and synchronization state\n- `brewfile add <package>` - Add package to configuration and install\n- `brewfile remove <package>` - Remove package from system and configuration\n- `brewfile edit` - Open configuration file in editor\n\n### Sync Commands\n\n- `brewfile sync-adopt` - Install missing packages + adopt extra packages to config (safe)\n- `brewfile sync-cleanup` - Install missing packages + remove extra packages (destructive)\n\n### Interactive Mode\n\nRun `brewfile` without arguments to enter interactive mode with guided workflows.\n\n## Advanced Usage\n\n### Package Types\n\nBrewfile automatically detects package types, but you can force specific types:\n\n```bash\nbrewfile add --cask chrome # Force as cask\nbrewfile add neovim # Auto-detect (formula)\n```\n\n### Machine-Specific Configurations\n\nConfigure different package sets for different machines by hostname:\n\n```json\n{\n \"machines\": {\n \"work-macbook\": [\"development\", \"work-tools\"],\n \"personal-imac\": [\"development\", \"gaming\", \"media\"]\n }\n}\n```\n\n### Mac App Store Apps\n\nInclude Mac App Store apps with app IDs:\n\n```bash\nbrewfile add \"Xcode::497799835\" # Format: AppName::AppID\n```\n\n## Configuration Management\n\n### Package Groups\n\nOrganize packages into logical groups:\n\n- **development**: Development tools and languages\n- **media**: Audio/video tools and entertainment\n- **work**: Work-specific applications\n- **gaming**: Games and gaming tools\n\n### Dotfiles Integration\n\n**Brewfile works exceptionally well with dotfiles management systems!** \ud83d\udd17\n\nFor multi-machine synchronization:\n\n1. **Store your config in dotfiles**: Add `~/.config/brewfile.json` to your dotfiles repository\n2. **Symlink on new machines**: Your dotfiles manager can symlink the config automatically\n3. **Machine-aware setup**: Different machines automatically get their appropriate package groups\n4. **One command setup**: Run `brewfile sync-adopt` on a new machine to get all your tools\n\n```bash\n# Example dotfiles setup\n# In your dotfiles repo:\n~/dotfiles/config/brewfile.json -> ~/.config/brewfile.json\n\n# On a new machine after dotfiles setup:\nbrewfile sync-adopt # Installs all packages for this machine\n```\n\nThis approach ensures consistent development environments across all your machines while respecting machine-specific needs (e.g., work laptop vs. personal desktop).\n\n### Best Practices\n\n1. Keep packages in appropriate groups\n2. Use machine-specific configurations for different setups\n3. Store your brewfile config in your dotfiles repository\n4. Regularly run `brewfile status` to maintain sync\n5. Use `sync-adopt` for safe operations, `sync-cleanup` when you need to clean up\n\n## Requirements\n\n- macOS (Homebrew is macOS-specific)\n- Python 3.9 or higher\n- Homebrew installed\n- Optional: `mas` for Mac App Store apps\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## Support\n\nIf you encounter issues or have questions:\n\n1. Check existing [GitHub Issues](https://github.com/waltermwaniki/brewfile/issues)\n2. Create a new issue with details about your problem\n3. Include your configuration file (with sensitive data removed)\n\n---\n\n**Happy brewing! \ud83c\udf7a**\n",
"bugtrack_url": null,
"license": null,
"summary": "Intelligent Homebrew package management using brew bundle with JSON configuration and machine-aware installations",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/waltermwaniki/brewfile",
"Issues": "https://github.com/waltermwaniki/brewfile/issues",
"Repository": "https://github.com/waltermwaniki/brewfile"
},
"split_keywords": [
"homebrew",
" brew",
" package-management",
" macos",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "87c9b4ed4ecc36599d03d10f5b2fd23a68922f6b15ba8cd7f31bd14f98d5ef36",
"md5": "a87dd710fd3292a07a5e7c20876fdb88",
"sha256": "4bb79e135efd2b08a3a6d79562e32c383ae01e629f06253a5fa2a617a5ae8904"
},
"downloads": -1,
"filename": "brewfile-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a87dd710fd3292a07a5e7c20876fdb88",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 17108,
"upload_time": "2025-09-09T01:30:58",
"upload_time_iso_8601": "2025-09-09T01:30:58.405371Z",
"url": "https://files.pythonhosted.org/packages/87/c9/b4ed4ecc36599d03d10f5b2fd23a68922f6b15ba8cd7f31bd14f98d5ef36/brewfile-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f73960d7d0e5bf5ea0f379d633465d0d1344d0e8b906134a540aaa60d3f45d4d",
"md5": "8a1e9b321d9b2da2d332279b9c121513",
"sha256": "d3ae55018f80c1f5ce305ca6ba8e3449ac9c7cff0464d88035087a6cb61fa797"
},
"downloads": -1,
"filename": "brewfile-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "8a1e9b321d9b2da2d332279b9c121513",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 17043,
"upload_time": "2025-09-09T01:30:59",
"upload_time_iso_8601": "2025-09-09T01:30:59.610010Z",
"url": "https://files.pythonhosted.org/packages/f7/39/60d7d0e5bf5ea0f379d633465d0d1344d0e8b906134a540aaa60d3f45d4d/brewfile-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-09 01:30:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "waltermwaniki",
"github_project": "brewfile",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "brewfile"
}
