Admin Unix

Unix Administration (macOS + Linux)

CRITICAL MUST: Secrets and .env

• NEVER store live .env files or credentials inside any skill folder.
• .env.template files belong only in templates/ within a skill.
• Store live secrets in ~/.admin/.env (or another non-skill location you control) and reference them from there.

Requires: macOS or native Linux (NOT WSL)

⚠️ Profile Gate (MANDATORY - DO THIS FIRST)

STOP. Before ANY operation, you MUST check for the profile. This is not optional.

Step 1: Check Profile Exists

~/.claude/skills/admin/scripts/test-admin-profile.sh

Returns JSON: {"exists":true,"path":"~/.admin/profiles/hostname.json",...}

Step 2: If Profile Missing → Run Setup

~/.claude/skills/admin/scripts/setup-interview.sh

DO NOT proceed with ANY task until profile exists.

Step 3: Load Profile

source ~/.claude/skills/admin/scripts/load-profile.sh
load_admin_profile
show_admin_summary

Platform Detection

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

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

macOS (Homebrew)

# Install
brew install $package

# Update
brew upgrade $package

# List
brew list

# Search
brew search $package

Linux (apt)

# 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)

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)

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)

# 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)

# 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:

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

Or manually:

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:

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

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

Scope Boundaries

References

• references/OPERATIONS.md - Common operations, troubleshooting