Mac OS - Aliases Management#

Quick Restore (Workstation Rebuild):

  1. Clone your scripts: git clone git@github.com:marcoue/Scripts.git ~/Scripts
  2. Run the restore script: source ~/Scripts/MacOS/Aliases/MacOS_Aliases_restore.sh
  3. Retrieve local secrets from your 1Password Homelab Vault under the entry Mac OS .zshrc file and copy them into your local ~/.zshrc (Edit using: nano ~/.zshrc).
  4. Refresh your shell configuration to apply the new tokens: source ~/.zshrc.

Related Recovery Guides: Master Checklist: Mac OS - Recovery | Packages Sync: Mac OS - Brewfile | Repository Standard: Scripts Mangement.

How to Add a New Alias:

  1. Open the tracked config: nano ~/Scripts/MacOS/Aliases/MacOS-Aliases.zsh
  2. Add your custom alias to the file (e.g., alias mycmd='some_command').
  3. Save, exit, and reload the terminal to apply: source ~/.zshrc
  4. Commit and push: Running the pushscripts alias will commit and push your updated aliases and package lists to GitHub (and mirror to NAS), or you can commit/push manually inside ~/Scripts.

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, 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 MacOS-Aliases.zsh. The restore script is managed at MacOS_Aliases_restore.sh.

2.1 Active Aliases Reference#

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

Backup & Sync#

Alias Command / Execution Description
pushlab bash ~/Scripts/MacOS/sync-obsidian-homelab-hugo.sh Syncs local Obsidian Homelab notes and images to Proxmox VM, builds Hugo site, and backs up vault to GitHub.
pushgen bash ~/Scripts/MacOS/sync-obsidian-gendash-hugo.sh Syncs local GenDash Obsidian notes to Proxmox VM and triggers a site build.
pushscripts cd ~/Scripts && git add . && git commit -m "Update scripts" && git push origin main Stages, commits, and pushes all changes in ~/Scripts/ to GitHub and NAS mirror.
pullscripts cd ~/Scripts && git pull origin main Pulls latest commits from GitHub to update local scripts repository.
pushbrew brew bundle dump --file=~/Scripts/MacOS/Brew/Brewfile --force && (cd ~/Scripts && git add MacOS/Brew/Brewfile && git commit -m "Auto-update Brewfile" && git push origin main) Dumps Homebrew package inventory (Brewfile) and commits/pushes it to remote repo.
pullbrew (cd ~/Scripts && git pull origin main) && brew bundle --file=~/Scripts/MacOS/Brew/Brewfile ... Pulls updates, installs missing packages from Brewfile, and interactively prompts for cleanup.

Utility & Workflows#

Alias Command / Execution Description
convert bash ~/Scripts/MacOS/convert_images_900.sh Scales local images down to 900px width.
convertsend bash ~/Scripts/MacOS/convert_raw_send_to_vm.sh Processes RAW images and uploads them directly to Proxmox VM.
speed bash ~/Scripts/MacOS/speed_test.sh Runs network diagnostic speed checks.
gitstatus python3 ~/Scripts/MacOS/git_status.py Scans all Git repositories on the workstation and prints status summary.
kvm ~/Scripts/MacOS/KVM-Launch.sh Opens Java Web Start utility to control Tripp Lite KVM switch.
netbox env -u OP_SERVICE_ACCOUNT_TOKEN python3 ~/Scripts/Linux/Netbox/Netbox_sync_gsheets_to_netbox.py Syncs homelab inventory from Google Sheets to NetBox using the personal 1Password session.

GenDash File Locking#

Alias Command / Execution Description
genl ~/Scripts/MacOS/lock_gendash.sh lock Locks GenDash files.
genu ~/Scripts/MacOS/lock_gendash.sh unlock Unlocks GenDash files.
gens ~/Scripts/MacOS/lock_gendash.sh status Checks GenDash file lock status.
genx ~/Scripts/MacOS/lock_gendash.sh lock-strings Locks resource string assets.

MCP & AI Tools Configuration#

Alias Command / Execution Description
mcp python3 ~/.mcp-config/apply.py Runs MCP settings compiler for all AI clients, then auto-commits & pushes changes to GitHub. (Pass targets like mcp codex)
codexa printf "%s" "<KEY>" | codex login --with-api-key (Local-only) Dynamically authenticates Codex-CLI with your OpenAI API key.

3. Local Configuration (~/.zshrc)#

The local .zshrc is stripped of general settings, functioning exclusively to store secrets and mount the tracked 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).

5. Related Notes#

Backward Linux Desktop Configuration Guide Mac OS - Brewfile Forward