---
name: admin-unix
description: "Native macOS and Linux administration (non-WSL). Profile-aware - reads preferences from ~/.admin/profiles/{hostname}.json.  Use when: macOS/Linux system admin, Homebrew (macOS), apt (Linux), services. NOT for WSL - use admin-wsl instead."
---

# Unix Administration

_Consolidated from `skills/admin (unix)` on 2026-02-02_

## Contents

- [Profile Gate](#profile-gate)
- [Platform Detection](#platform-detection)
- [Package Management (Profile-Aware)](#package-management-profile-aware)
- [Python Commands (Profile-Aware)](#python-commands-profile-aware)
- [Node Commands (Profile-Aware)](#node-commands-profile-aware)
- [Services](#services)
- [SSH to Servers](#ssh-to-servers)
- [Update Profile](#update-profile)
- [Capabilities Check](#capabilities-check)
- [Scope Boundaries](#scope-boundaries)
- [References](#references)
- [Logging (Centralized)](#logging-centralized)
- [Linux (apt): Standard Workflow](#linux-apt-standard-workflow)
- [Linux (apt): Common Errors + Fixes](#linux-apt-common-errors--fixes)
- [Linux (systemd): Common Operations](#linux-systemd-common-operations)
- [macOS (Homebrew): Standard Workflow](#macos-homebrew-standard-workflow)
- [macOS (Homebrew): PATH Notes (Apple Silicon)](#macos-homebrew-path-notes-apple-silicon)
- [macOS (Homebrew): Services](#macos-homebrew-services)
- [macOS (Homebrew): Common Errors + Fixes](#macos-homebrew-common-errors--fixes)
- [Troubleshooting Checklist](#troubleshooting-checklist)

**Requires**: macOS or native Linux (NOT WSL)

---

## Profile Gate

Run the profile check before any operation. See `references/profile-gate.md` for full details.

```bash
scripts/test-admin-profile.sh
```

If `exists: false`, run the TUI setup interview (see profile-gate.md) before proceeding.

---

## Platform Detection

```bash
OS=$(uname -s)
case "$OS" in
    Darwin) echo "macOS" ;;
    Linux)  
        if grep -qi microsoft /proc/version 2>/dev/null; then
            echo "WSL - use admin (wsl) instead"
        else
            echo "Native Linux"
        fi
        ;;
esac
```

---

## Package Management (Profile-Aware)

### Check Preference

```bash
PKG_MGR=$(jq -r '.preferences.packages.manager' "$PROFILE_PATH")
```

### macOS (Homebrew)

```bash
# Install
brew install $package

# Update
brew upgrade $package

# List
brew list

# Search
brew search $package
```

### Linux (apt)

```bash
# Update index
sudo apt update

# Install
sudo apt install -y $package

# Upgrade all
sudo apt upgrade -y

# Search
apt search $package
```

---

## Python Commands (Profile-Aware)

```bash
PY_MGR=$(get_preferred_manager python)

case "$PY_MGR" in
    uv)     uv pip install "$package" ;;
    pip)    pip3 install "$package" ;;
    conda)  conda install "$package" ;;
esac
```

---

## Node Commands (Profile-Aware)

```bash
NODE_MGR=$(get_preferred_manager node)

case "$NODE_MGR" in
    npm)    npm install "$package" ;;
    pnpm)   pnpm add "$package" ;;
    yarn)   yarn add "$package" ;;
    bun)    bun add "$package" ;;
esac
```

---

## Services

### Linux (systemd)

```bash
# Status
sudo systemctl status $service

# Start/Stop/Restart
sudo systemctl start $service
sudo systemctl stop $service
sudo systemctl restart $service

# Enable/Disable on boot
sudo systemctl enable $service
sudo systemctl disable $service

# View logs
journalctl -u $service -f
```

### macOS (Homebrew services)

```bash
# List
brew services list

# Start/Stop
brew services start $service
brew services stop $service
brew services restart $service
```

---

## SSH to Servers

Use profile server data:

```bash
ssh_to_server "cool-two"  # Helper from load-profile.sh
```

Or manually:

```bash
SERVER=$(jq '.servers[] | select(.id == "cool-two")' "$PROFILE_PATH")
HOST=$(echo "$SERVER" | jq -r '.host')
USER=$(echo "$SERVER" | jq -r '.username')
KEY=$(echo "$SERVER" | jq -r '.keyPath')

ssh -i "$KEY" "$USER@$HOST"
```

---

## Update Profile

After installing a tool:

```bash
PROFILE=$(cat "$PROFILE_PATH")
PROFILE=$(echo "$PROFILE" | jq --arg ver "$(python3 --version | cut -d' ' -f2)" \
    '.tools.python.version = $ver | .tools.python.present = true')
echo "$PROFILE" | jq . > "$PROFILE_PATH"
```

---

## Capabilities Check

```bash
has_capability "hasDocker" && docker info
has_capability "hasGit" && git --version
```

---

## Scope Boundaries

| Task | Handle Here | Route To |
|------|-------------|----------|
| Homebrew (macOS) | ✅ | - |
| apt (Linux) | ✅ | - |
| systemd services | ✅ | - |
| Python/Node | ✅ | - |
| WSL operations | ❌ | admin (wsl) |
| Windows operations | ❌ | admin (windows) |
| Server provisioning | ❌ | devops |

---

## References

- `references/OPERATIONS.md` - Common operations, troubleshooting

### unix: references/OPERATIONS.md

# Unix Operations Reference

Extended operations for macOS and Linux administration (outside of WSL). This file is expanded in later phases; keep `SKILL.md` as the overview.

---

## Platform Detection

```bash
uname -s
# Darwin → macOS
# Linux  → Linux (native). If in WSL, use admin (wsl).
```

WSL detection:

```bash
grep -qi microsoft /proc/version 2>/dev/null && echo "wsl"
```

If this returns `wsl`, use `admin (wsl)` instead of `admin (unix)`.

---

## Logging (Centralized)

Prefer the `admin` logging functions:

- `admin/references/logging.md`

Quick examples:

```bash
log_admin "SUCCESS" "installation" "Installed package" "pkg=<PKG>"
log_admin "SUCCESS" "operation" "Updated system" "method=apt"
log_admin "ERROR" "operation" "Command failed" "cmd=<CMD> exit=<CODE>"
```

---

## Linux (apt): Standard Workflow

Use these steps for Debian/Ubuntu systems.

### 0. Identify distro and version (for correct packages)

```bash
cat /etc/os-release
uname -a
```

### 1. Update package lists and upgrade

```bash
sudo apt update
sudo apt upgrade -y
```

If you changed sources recently:

```bash
sudo apt update --allow-releaseinfo-change
```

Log:

```bash
log_admin "SUCCESS" "operation" "Updated system packages" "method=apt"
```

### 2. Install packages

```bash
sudo apt install -y <PKG>
```

Verify install:

```bash
dpkg -l | rg -n "^ii\\s+<PKG>\\b" || true
apt-cache policy <PKG>
command -v <CMD> || true
<CMD> --version || true
```

Log:

```bash
log_admin "SUCCESS" "installation" "Installed package" "pkg=<PKG> method=apt"
```

### 3. Remove packages

```bash
sudo apt remove -y <PKG>
sudo apt autoremove -y
```

For config purge:

```bash
sudo apt purge -y <PKG>
```

Log:

```bash
log_admin "SUCCESS" "installation" "Removed package" "pkg=<PKG> method=apt"
```

### 4. Search packages

```bash
apt-cache search <TERM>
apt-cache show <PKG> | sed -n '1,120p'
```

### 5. Hold/unhold packages (pin versions)

```bash
sudo apt-mark hold <PKG>
apt-mark showhold
sudo apt-mark unhold <PKG>
```

### 6. Cleanup

```bash
sudo apt autoremove -y
sudo apt clean
```

```bash
sudo apt update
sudo apt upgrade -y
sudo apt install -y <PKG>
sudo apt remove -y <PKG>
apt-cache policy <PKG>
```

---

## Linux (apt): Common Errors + Fixes

### Error: Could not get lock (another apt/dpkg process)

Symptoms:
- `Could not get lock /var/lib/dpkg/lock-frontend`
- `Unable to acquire the dpkg frontend lock`

Steps:

```bash
ps aux | rg -n \"apt|dpkg\" || true
sudo lsof /var/lib/dpkg/lock-frontend 2>/dev/null || true
sudo lsof /var/lib/dpkg/lock 2>/dev/null || true
```

If you confirm it’s a stuck process (not actively running upgrades), stop it carefully and retry:

```bash
sudo apt update
```

Log failures:

```bash
log_admin "ERROR" "operation" "apt lock prevented update" "path=/var/lib/dpkg/lock-frontend"
```

### Error: dpkg was interrupted

Symptoms:
- `dpkg was interrupted, you must manually run 'sudo dpkg --configure -a'`

Fix:

```bash
sudo dpkg --configure -a
sudo apt -f install
sudo apt update
sudo apt upgrade -y
```

### Error: Unmet dependencies / held broken packages

```bash
sudo apt --fix-broken install
sudo apt -f install
apt-mark showhold
```

If a package is held:

```bash
sudo apt-mark unhold <PKG>
sudo apt install -y <PKG>
```

### Error: Temporary failure resolving (DNS)

```bash
cat /etc/resolv.conf
ping -c 1 1.1.1.1 || true
ping -c 1 deb.debian.org || true
```

Log:

```bash
log_admin "ERROR" "operation" "DNS resolution failed" "host=deb.debian.org"
```

### Error: Release file changed / repository metadata changed

```bash
sudo apt update --allow-releaseinfo-change
```

### Error: Hash Sum mismatch

```bash
sudo rm -rf /var/lib/apt/lists/*
sudo apt clean
sudo apt update
```

---

## Linux (systemd): Common Operations

```bash
# Status and logs
sudo systemctl status <SERVICE>
sudo journalctl -u <SERVICE> --no-pager -n 200
sudo journalctl -u <SERVICE> -f

# Start/stop/restart
sudo systemctl start <SERVICE>
sudo systemctl stop <SERVICE>
sudo systemctl restart <SERVICE>

# Enable/disable at boot
sudo systemctl enable <SERVICE>
sudo systemctl disable <SERVICE>

# After editing unit files
sudo systemctl daemon-reload
sudo systemctl restart <SERVICE>

# Discover services
systemctl list-units --type=service --state=running
```

---

## macOS (Homebrew): Standard Workflow

```bash
# Verify platform
uname -s
# Darwin → macOS

# Verify brew
brew --version
command -v brew
brew config
```

### Install Homebrew (if missing)

Use the official installer. This requires network access.

```bash
/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"
```

Log:

```bash
log_admin "SUCCESS" "installation" "Installed Homebrew" "method=brew-install"
```

### Update and upgrade

```bash
brew update
brew upgrade
brew cleanup
```

Log:

```bash
log_admin "SUCCESS" "operation" "Updated brew packages" "method=brew"
```

### Install and uninstall formulae

```bash
brew install <FORMULA>
brew uninstall <FORMULA>
brew list --formula
brew info <FORMULA>
```

Verify installed formula and binary:

```bash
brew --prefix <FORMULA>
command -v <CMD> || true
<CMD> --version || true
```

Log:

```bash
log_admin "SUCCESS" "installation" "Installed formula" "formula=<FORMULA> method=brew"
```

### Pin / unpin (freeze versions)

```bash
brew pin <FORMULA>
brew unpin <FORMULA>
brew list --pinned
```

---

## macOS (Homebrew): PATH Notes (Apple Silicon)

If `brew` is installed but not found, you almost always have a PATH issue.

Common locations:

- Apple Silicon: `/opt/homebrew/bin/brew`
- Intel: `/usr/local/bin/brew`

Check:

```bash
ls -la /opt/homebrew/bin/brew /usr/local/bin/brew 2>/dev/null || true
```

Recommended shell setup:

```bash
# Apple Silicon default
echo 'eval \"$(/opt/homebrew/bin/brew shellenv)\"' >> ~/.zprofile
eval \"$(/opt/homebrew/bin/brew shellenv)\"
```

If your shell is bash:

```bash
echo 'eval \"$(/opt/homebrew/bin/brew shellenv)\"' >> ~/.bash_profile
eval \"$(/opt/homebrew/bin/brew shellenv)\"
```

Re-check:

```bash
brew --version
```

---

## macOS (Homebrew): Services

Some formulae provide background services via `brew services`:

```bash
brew services list
brew services start <FORMULA>
brew services restart <FORMULA>
brew services stop <FORMULA>
```

Log:

```bash
log_admin "SUCCESS" "system-change" "Updated brew service" "service=<FORMULA> action=start"
```

---

## macOS (Homebrew): Common Errors + Fixes

### Error: `brew` not found

Use the PATH guidance above and re-check:

```bash
command -v brew || true
```

### Error: `brew doctor` reports issues

Run:

```bash
brew doctor
```

Then apply the minimal changes it recommends (avoid random permission changes).

### Error: Xcode Command Line Tools missing

Symptoms:
- compilers missing, `git` missing, build errors

Fix:

```bash
xcode-select --install
```

### Error: Update/upgrade fails intermittently

```bash
brew update
brew doctor
brew config
```

Log failures:

```bash
log_admin "ERROR" "operation" "brew update failed" "check=brew-doctor"
```

---

## Troubleshooting Checklist

- Confirm platform (`uname -s`) and avoid WSL-only paths unless you are in WSL.
- If you detect WSL (`grep -qi microsoft /proc/version`), use `admin (wsl)`.
- Confirm tool path:
  - `command -v <CMD>`
  - `which <CMD>`
- For permissions issues:
  - `ls -la <PATH>`
  - `stat <PATH>`
- For services:
  - Linux: `systemctl status`, `journalctl -u`
  - macOS: `brew services list`


---
Source attribution: evolv3-ai
Original project: https://github.com/evolv3-ai/vibe-skills/blob/c99e543ccfb9a505b32f22f99e416c479d6094bb/plugins/admin-devops/skills/admin/references/unix.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Dave AI.

## Upstream license notice

MIT License

Copyright (c) 2025 Jeremy Dawes (Jezweb)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Dave AI resource metadata

Creator / publisher: evolv3-ai
Original project: https://github.com/evolv3-ai/vibe-skills/blob/c99e543ccfb9a505b32f22f99e416c479d6094bb/plugins/admin-devops/skills/admin/references/unix.md
Attribution basis: Recovered original package and original project license at a pinned revision

Fields of work: Development & Engineering, Customer Support
Roles: Backend Developer, DevOps / SRE, Technical Support
Specialties: Backend, DevOps
Tools: Apt, Homebrew, Jq, Ssh
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 3d69d96ee869066522051e9843480cd64fcacb715f8bde90e8239ec0f351855a
Metadata reviewed: 2026-10-27
This metadata supersedes earlier Dave AI catalog attribution. Original instruction and supporting files are preserved.