Documentation

A reusable Bash helper library for macOS administrators.

Concept app. A working exploration of an idea, built and shared to show what's possible — not a supported commercial product. Expect rough edges, no SLA and no roadmap guarantees. It has been tested in a demo environment only, not in production. Try it on test Macs first; feedback is very welcome.

Overview

macAdmin Library provides the small set of functions macOS admins tend to reimplement in every new script — in one library under one naming scheme. The project started as mac-admin-bash-lib in February 2026 and has grown from a nine-function skeleton into about 190 modules and more than 1,200 functions (in the committed repository).

Where it stands: a prototype, being reorganised. The app modules are generated from Installomator labels; about 64 of ~150 still hold placeholder installer URLs (example.com) pending vendor research, and the rest haven't been checked against the vendors by me. The repository has no licence file yet and no CI workflow — shellcheck, shfmt and the bats tests run locally through make — and I haven't run them for this page. Treat everything as a starting point, not a vetted dependency.

Namespacing: every public function is namespaced as maclib::<module>::<name>, so it's always clear which module a function came from and safe to source alongside your own code.

Installation

There's no package manager distribution yet — clone the repository and source the library entrypoint directly from your scripts:

git clone https://github.com/Spectrechen/mac-admin-bash-lib.git

Quick Start

# Source the library entrypoint
source ./lib/maclib.sh

maclib::log::set_level info
maclib::log::info "Hello from maclib"

if maclib::os::is_macos; then
  maclib::log::info "macOS $(maclib::os::version) on $(maclib::os::arch)"
fi

See examples/demo.sh in the repository for a complete runnable example.

Modules

The committed repository has 189 module files and about 1,250 functions under lib/, sourced through lib/maclib.sh. The full per-function list is docs/function-catalog.md in the repository.

Group	Modules	What's in it
core	12	`log`, `os`, `user`, `system` (software update, SIP, `system_profiler`), `packages`, `signing` (codesign, notarize, staple), `filevault`, `keychain`, `launchd`, `network`, `management` (MDM status, profiles), `app`
mdm	1	`jamf`: eleven Jamf extension-attribute helpers (battery, security chip, kexts, system extensions, uptime, Xcode CLT, startup volume, charger wattage, Time Machine, Homebrew)
security	1	Audit framework with Gatekeeper, application firewall and SSH checks and remediation
apps, browsers, communication, productivity, ai, creative, devops, media, cloud_storage, security_tools	~175	Per-app helpers: installer URL, latest version, installed check and path, and install/uninstall helpers where documented. About 150 of them live in `apps/`; the hand-researched ones (for example Chrome, Firefox, Zoom, Slack, 1Password, Office for Mac) cite their vendor notes in `docs/`

The original nine functions, still the foundation:

Module	Function	Description	Notes
logging	`maclib::log::set_level`	Set the global log level	debug / info / warn / error
logging	`maclib::log::debug` / `info`	Log messages	stdout
logging	`maclib::log::warn` / `error`	Log warnings and errors	stderr
os	`maclib::os::is_macos`	Check if running on macOS	—
os	`maclib::os::version`	Full macOS product version	uses `sw_vers`
os	`maclib::os::major_minor`	Major.Minor version only	—
os	`maclib::os::arch`	CPU architecture	`uname -m`

Names are in flux. A reorganisation that puts each app module under its category (for example maclib::chatgpt::url becoming maclib::ai::chatgpt::url) is in progress and not yet published. Pin to a commit if you depend on a function name.

Logging Module (`lib/core/log.sh`)

All logging goes through a single global level (default: info). debug and info messages go to stdout so they stay part of a script's data output when needed; warn and error go to stderr, keeping diagnostics separate from data.

OS Module (`lib/core/os.sh`)

Small helpers for the platform checks admin scripts need constantly: whether you're even running on macOS, the exact OS version, just the major.minor pair, and CPU architecture — useful for branching logic between Apple Silicon and Intel, or gating a feature to a minimum OS version.

Conventions

Target shell is Bash — this is a macOS admin scripting library, not a POSIX-portable one.
Public functions: maclib::<module>::<name>. Internal helpers: _maclib::<module>::<name> or __maclib_*.
Library code is safe under set -euo pipefail.
eval is never used; variables are always quoted.
Temp files/dirs use mktemp and are always cleaned up.
Inputs (paths, URLs) are validated where it matters.
The repository's agent guidelines say no code is copied from other projects unless its licence and attribution are verified. The app modules are derived from Installomator labels; the library is licensed under Apache 2.0, the same licence as Installomator, and the repository's NOTICE file credits Installomator.

Testing & Linting

Prerequisites: shellcheck, shfmt, bats-core. The repository has a Makefile but no CI workflow yet, so run these yourself.

make lint   # shellcheck
make fmt    # shfmt -w -i 2 -ci -bn
make test   # bats-core test suite

New functions should ship with a bats test under tests/. Where behavior depends on macOS-specific commands, tests isolate them via wrappers/mocks rather than requiring a real macOS environment.

Documentation

Overview

Installation

Quick Start

Modules

Logging Module (lib/core/log.sh)

OS Module (lib/core/os.sh)

Conventions

Testing & Linting

Logging Module (`lib/core/log.sh`)

OS Module (`lib/core/os.sh`)