carapace-sh/carapace-bin / skills/brew
brew
VerifiedUse when working with Homebrew (`brew`) — the package manager for macOS and Linux. Covers the command structure, formula and cask DSLs, taps, bottles, the Cellar, services, bundle/Brewfile, environment variables, installation internals, and developer commands. Triggers on: "brew", "homebrew", "brew install", "brew uninstall", "brew update", "brew upgrade", "brew search", "brew tap", "brew cask", "brew bottle", "brew services", "brew bundle", "brew cleanup", "brew doctor", "brew audit", "brew livecheck", "brew test-bot", "brew bump-formula-pr", "Brewfile", "HOMEBREW_PREFIX", "HOMEBREW_CELLAR", "HOMEBREW_NO_INSTALL_FROM_API", "HOMEBREW_CASK_OPTS", "HOMEBREW_BOTTLE_DOMAIN", "Formula", "Cask", "Cellar", "Caskroom", "keg", "rack", "tap", "bottle", "superenv", "Formulary", "FormulaInstaller", "shellenv", "restart_service", "keg-only", "brew deps", "brew uses", "brew leaves", "brew outdated", "brew pin", "brew fetch", "brew create", "brew edit", "livecheck", "auto_updates", "depends_on".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.8 KB |
| references/bottle.md | markdown | 5.3 KB |
| references/bundle.md | markdown | 9.1 KB |
| references/cask.md | markdown | 13.0 KB |
| references/cellar.md | markdown | 7.2 KB |
| references/commands.md | markdown | 11.7 KB |
| references/dependency.md | markdown | 3.9 KB |
| references/developer.md | markdown | 13.2 KB |
| references/environment.md | markdown | 11.8 KB |
| references/formula.md | markdown | 11.8 KB |
| references/maintenance.md | markdown | 5.9 KB |
| references/services.md | markdown | 6.9 KB |
| references/taps.md | markdown | 5.1 KB |
references/services.md
View on GitHub# Services
`brew services` manages background services via `launchctl` (macOS) or `systemctl` (Linux). This document covers the `services` command, the `service do` DSL block in formulae, and the launchd/systemd integration.
## `brew services` Subcommands
| Subcommand | Purpose |
|------------|---------|
| `brew services list` | List all managed services |
| `brew services start <formula\|--all>` | Start and register service (auto-launch at login/boot) |
| `brew services stop <formula\|--all>` | Stop and unregister service |
| `brew services restart <formula\|--all>` | Stop (if needed) and start, register |
| `brew services run <formula\|--all>` | Run without registering (no auto-launch) |
| `brew services kill <formula\|--all>` | Stop but keep registered |
| `brew services info <formula\|--all>` | Show service info |
| `brew services cleanup` | Remove all unused services |
### Key Distinction: `start` vs `run`
| Command | Runs now? | Registers for auto-launch? |
|---------|----------|---------------------------|
| `start` | Yes | Yes |
| `run` | Yes | No |
| `stop` | No (stops) | No (unregisters) |
| `kill` | No (stops) | Yes (keeps registration) |
| `restart` | Yes | Yes |
### Flags
| Flag | Applies to | Purpose |
|------|-----------|---------|
| `--all` | start, stop, restart, run, kill, info | Operate on all services |
| `--file <path>` | start, restart, run | Use a custom service file |
| `--json` | list, info | JSON output |
| `--keep` | stop | Don't unregister from launchd/systemd |
| `--no-wait` | stop | Don't wait for service to stop |
| `--sudo-service-user <user>` | start (root/macOS) | Run service as specific user |
### User vs System Services
| Scope | macOS Location | Linux Location | Starts at |
|-------|---------------|----------------|-----------|
| **User** (no sudo) | `~/Library/LaunchAgents` | `~/.config/systemd/user` | Login |
| **System** (with sudo) | `/Library/LaunchDaemons` | `/usr/lib/systemd/system` | Boot |
Prepend `sudo` to operate system-wide:
```bash
sudo brew services start nginx # system-wide (starts at boot)
brew services start nginx # user-level (starts at login)
```
## launchctl vs systemctl Integration
| Aspect | macOS | Linux |
|--------|-------|-------|
| **Manager** | `launchctl` (via `launchd`) | `systemctl` (via `systemd`) |
| **Service files** | `.plist` files | `.service` files |
| **User scope** | `~/Library/LaunchAgents` | `~/.config/systemd/user` |
| **System scope** | `/Library/LaunchDaemons` | `/usr/lib/systemd/system` |
Homebrew generates `.plist` (macOS) or `.service` (Linux) files from the formula's `service do` block and places them in the appropriate location.
## The `service do` Block in Formulae
The `service` block in a formula defines background services. There are two approaches:
### 1. Package-Provided Service File
If the software already ships a `launchd` plist or `systemd` service file, install it into the prefix and reference it by name:
```ruby
service do
name macos: "custom.launchd.name",
linux: "custom.systemd.name"
end
```
Homebrew appends `.plist` (macOS) or `.service` (Linux) to the name to locate the file.
### 2. Formula-Defined Service File
Generate a service file inline:
```ruby
# Single command
service do
run opt_bin/"script"
end
# Command with arguments
service do
run [opt_bin/"script", "--config", etc/"config.yml"]
end
# OS-specific commands
service do
run macos: [opt_bin/"macos_script", "standalone"],
linux: var/"special_linux_script"
end
```
## Service Block Methods
The `run` or `name` field **must** be defined. If `name` is defined without `run`, Homebrew uses the package-provided file unchanged.
| Method | Default | macOS | Linux | Description |
|--------|---------|-------|-------|-------------|
| `run` | — | yes | yes | Command to execute (array with args or path) |
| `run_type` | `:immediate` | yes | yes | `:immediate`, `:interval`, or `:cron` |
| `interval` | — | yes | yes | Start interval in seconds (for `:interval`) |
| `cron` | — | yes | yes | Crontab syntax (for `:cron`) |
| `keep_alive` | `false` | yes | yes | Conditions for staying alive |
| `launch_only_once` | `false` | yes | yes | Run only once, no restart |
| `require_root` | `false` | yes | yes | Hint that service needs root |
| `environment_variables` | — | yes | yes | Hash of env vars |
| `working_dir` | — | yes | yes | Working directory |
| `root_dir` | — | yes | yes | Chroot directory |
| `input_path` | — | yes | yes | Input path |
| `log_path` | — | yes | yes | stdout log path |
| `error_log_path` | — | yes | yes | stderr log path |
| `restart_delay` | — | yes | yes | Seconds before restart |
| `throttle_interval` | — | yes | **no-op** | Min seconds between invocations (macOS default 10) |
| `process_type` | — | yes | **no-op** | `:background`, `:standard`, `:interactive`, `:adaptive` |
| `macos_legacy_timers` | — | yes | **no-op** | Don't coalesce launchd timers |
| `sockets` | — | yes | **no-op** | Socket definition: `<type>://<host>:<port>` |
| `nice` | — | yes | yes | Scheduling priority (-20 to 19; negative requires `require_root`) |
| `name` | — | yes | yes | Hash with `macos:` and/or `linux:` service name |
### `run_type`
| Type | Behavior |
|------|---------|
| `:immediate` (default) | Start immediately, keep alive |
| `:interval` | Run on repeating interval (requires `interval`) |
| `:cron` | Run at specific times (requires `cron` in crontab syntax) |
```ruby
service do
run [opt_bin/"cleanup"]
run_type :interval
interval 500
end
service do
run [opt_bin/"backup"]
run_type :cron
cron "5 * * * *"
end
```
### `keep_alive`
| Form | Behavior |
|------|---------|
| `keep_alive true` | Always keep alive |
| `keep_alive false` | Don't keep alive (run once) |
| `keep_alive always: true` | Same as `true` (hash form) |
| `keep_alive successful_exit: true` | Keep alive until non-zero exit |
| `keep_alive crashed: true` | Keep alive only if crashed |
| `keep_alive path: "/some/path"` | Keep alive while file exists |
### `environment_variables`
```ruby
service do
run opt_bin/"beanstalkd"
environment_variables PATH: std_service_path_env
end
```
The helper `std_service_path_env` returns `#{HOMEBREW_PREFIX}/bin:#{HOMEBREW_PREFIX}/sbin:/usr/bin:/bin:/usr/sbin:/sbin`.
### `sockets`
Format: `<type>://<host>:<port>` where type is `udp` or `tcp`.
```ruby
# Single socket (default name "listeners")
service do
run [opt_bin/"server"]
sockets "tcp://127.0.0.1:80"
end
# Multiple named sockets
service do
run [opt_bin/"server"]
sockets http: "tcp://0.0.0.0:80", https: "tcp://0.0.0.0:443"
end
```
> `sockets`, `throttle_interval`, `process_type`, and `macos_legacy_timers` are **no-op on Linux**.
## References
- [Formula Cookbook — Service files](https://docs.brew.sh/Formula-Cookbook#service-files)
- [Manpage — services subcommand](https://docs.brew.sh/Manpage#services-subcommand)
- For formula DSL: [formula.md](formula.md)
- For bundle service options: [bundle.md](bundle.md)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |