Updated: October 18, 2026

Mac OS - Aliases Management#

Keep Mac Studio and MacBook Air in Sync

The Mac Studio is the source of truth for the shared aliases. Edit and publish changes there, then pull them onto the MacBook Air.

On the Mac Studio — edit and publish:

nano ~/Scripts/MacOS/Aliases/MacOS-Aliases.zsh
source ~/.zshrc
pushscripts

pushscripts commits and pushes pending changes in the ~/Scripts repository.

On the MacBook Air — download and apply:

pullscripts
source ~/.zshrc

If an open terminal still shows old aliases, open a new terminal window. The shared aliases are in ~/Scripts/MacOS/Aliases/MacOS-Aliases.zsh; ~/.zshrc is local to each Mac and must source that file.

Set up a rebuilt Mac: Clone the repository with git clone git@github.com:marcoue/Scripts.git ~/Scripts, then restore the private ~/.zshrc settings from the 1Password Homelab vault entry Mac OS .zshrc file. Ensure it sources the shared alias file, then run source ~/.zshrc.

Related guides: Mac OS - Recovery · Mac OS - Brewfile · Scripts Mangement.

1. Overview & Architecture#

This note outlines the strategy for version-controlling and managing macOS shell aliases and environment paths. By separating configuration logic from local secrets, you can track your entire command shortcut suite in version control while keeping sensitive credentials secure.

1.1 The Split-Profile Architecture#

To protect sensitive API tokens while version-controlling workflow paths, the shell configuration is split into two files:

1. Tracked Configuration (~/Scripts/MacOS/Aliases/MacOS-Aliases.zsh):
   • Managed inside your existing Scripts Git repository.
   • Pushed to GitHub and auto-mirrored to your UNAS-Pro NAS.
   • Houses all custom aliases (pushlab, pulllab, pushbrew, kvm, etc.) and system environment paths.
2. Local Profile (~/.zshrc):
   • Kept local-only and untracked (excluded from Git).
   • Houses private system keys and service account tokens.
   • Automatically sources the tracked aliases file at startup.

2. Tracked Configurations (~/Scripts/MacOS/Aliases/MacOS-Aliases.zsh)#

All non-sensitive command aliases, system paths, and environment settings are migrated to the central scripts repository.

The file is managed directly in version control at ~/Scripts/MacOS/Aliases/MacOS-Aliases.zsh. The local ~/.zshrc profile is maintained separately and restored manually from the 1Password entry documented below; no restore script is required.

2.1 Active Aliases Reference#

Here is a quick reference table of all active shell aliases managed in your environment:

Backup & Sync#

Utility & Workflows#

GenDash File Locking#

GPSDash File Locking#

SoundDash File Locking#

DockDash File Locking#

MCP & AI Tools Configuration#

2.2 MCP Synchronization Functions#

pushmcp and pullmcp operate on the separate ~/.mcp-config repository, not on ~/Scripts. They are loaded from the tracked aliases file when ~/.zshrc sources it.

pushmcp() {
    (
        cd "$HOME/.mcp-config" || return
        git add -- config.json apply.py bin/macos-mcp-wrapper
        if ! git diff --cached --quiet; then
            git commit -m "Update MCP configuration" || return
        fi
        git push origin main
    )
}

alias pullmcp='(cd "$HOME/.mcp-config" && git pull origin main)'

The post-commit and post-merge hooks in ~/.mcp-config/.git/hooks/ run apply.py after the corresponding Git operation, compiling the MCP configuration for the registered AI clients.

3. Local Configuration (~/.zshrc)#

The local .zshrc is maintained manually and kept out of version control. It stores private settings and sources the tracked aliases file.

3.1 NetBox and 1Password Account Context#

The NetBox item is stored in the personal Homelab vault. The service account used by MCP is intentionally restricted to the Homelab-MCP vault and must not be granted access to Homelab.

Therefore, the netbox alias removes OP_SERVICE_ACCOUNT_TOKEN only from the NetBox process with env -u. This does not disconnect or remove the service account from the shell or from MCP.

On a Mac where the personal 1Password session has not yet been initialized, run this once:

eval "$(env -u OP_SERVICE_ACCOUNT_TOKEN op signin)"

Verify access without exposing secret values:

env -u OP_SERVICE_ACCOUNT_TOKEN op whoami
env -u OP_SERVICE_ACCOUNT_TOKEN op read \
  'op://Homelab/netbox/add more/GOOGLE_CLIENT_ID' >/dev/null

After pulling an alias update, reload the shell with source ~/.zshrc.

Secrets Backup: The exact values for the private keys and tokens below are securely stored in your 1Password Homelab vault under the entry Mac OS .zshrc file. Refer to that entry during a system rebuild to restore your local profile.

3.2 Local Profile Structure#

Below is how your local ~/.zshrc file will look:

# Location: ~/.zshrc
# (This file is local-only and not committed to GitHub)

# 1. Private Security Tokens & API Keys
export OP_SERVICE_ACCOUNT_TOKEN="<YOUR_1PASSWORD_SERVICE_ACCOUNT_TOKEN>"
export OP_BIOMETRIC_UNLOCK_ENABLED=false
export ANTHROPIC_BASE_URL="http://localhost:11434/v1"
export ANTHROPIC_API_KEY="ollama"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

# Codex-CLI API Key Alias
alias codexa='printf "%s" "<YOUR_OPENAI_API_KEY>" | codex login --with-api-key'

# 2. Source the Tracked Aliases File
if [ -f "$HOME/Scripts/MacOS/Aliases/MacOS-Aliases.zsh" ]; then
    source "$HOME/Scripts/MacOS/Aliases/MacOS-Aliases.zsh"
fi

4. Implementation Plan#

To deploy this configuration management setup, complete the following tasks:

• 4.1 Create MacOS-Aliases.zsh File: Extract all paths and aliases from the active ~/.zshrc and save them to /Users/marc/Scripts/MacOS/Aliases/MacOS-Aliases.zsh.
• 4.2 Clean Local .zshrc: Remove the moved configurations from /Users/marc/.zshrc and append the block to source the new file.
• 4.4 Commit & Sync Repository: Add MacOS-Aliases.zsh to your scripts repository, commit the changes, and push them to GitHub (which will mirror it to the NAS).

Validation for this setup is complete: reload ~/.zshrc, confirm aliases and functions with alias or whence -f, and run the read-only gitstatus command. Review changes before committing or pushing the Scripts repository.

5. Related Notes#

• Master Checklist: Mac OS - Recovery
• Software Configuration: Mac OS - Brewfile
• Linux Shortcuts: Linux - Aliases
• MCP Configuration: MCP Configuration Guide