macos

name	macos
description	Use the local `macos` CLI to scaffold, run, sign, notarize, and release native macOS menu bar apps. Triggers on creating a new menu bar app, running/building/signing a macOS app, setting up Developer ID signing or notarization, cutting a release with Sparkle auto-update, generating a Homebrew cask, or managing the macOS app inventory under ~/apps/macos.

macos CLI

Operates the macOS menu bar app platform (~/blueprints/macos). Each app is its own repo; by default it scaffolds to ~/apps/macos/<slug>, but the location is configurable (appsRoot in ~/.config/macos/config.json, or macos new --path … per app) and the inventory tracks where each app actually lives. SwiftPM + AppKit NSStatusItem + SwiftUI rows; Developer-ID-direct distribution with Sparkle auto-update and a Homebrew cask.

First, always

Run macos doctor to see toolchain + signing state. If signing/notary/Sparkle are missing, run macos signing setup (interactive, idempotent) before any build that needs to be distributed. Config: ~/.config/macos/config.json. Secrets: ~/.config/macos/secrets/ (never in a repo).

Common flows

New app

macos new <slug> --name "Display Name"        # add --api for networking + oauth + credentials
macos dev <slug>                              # build, ad-hoc sign, launch into the menu bar

Iterate

macos dev <slug>            # the dev loop (no Keychain/Sparkle noise)
macos audit <slug>          # blueprint compliance

Release (Developer ID direct)

# finalize CHANGELOG.md (date the top section) first
macos bump <slug> --version X.Y.Z
macos release <slug> --dry-run                # preview every step
macos release <slug>                          # build → notarize → GitHub release → appcast → cask

Command reference

• macos doctor [app] — toolchain + signing + credential checks with fix hints.
• macos signing setup [identity|notary|sparkle|tap] — guided onboarding.
• macos new <slug> / macos apps / macos inspect <app> / macos audit <app>.
• macos dev|build|sign|appcast|release <app> — the build → ship pipeline.
• macos bump <app> [--build|--version X.Y.Z], macos icons <app> --from icon-1024.png.
• macos homebrew <app>, macos modules ls|update <app> [module].

Rules

• Never put signing/notary/Sparkle secrets in an app repo — they belong in ~/.config/macos.
• app.config.json is the per-app source of truth; the CLI and Scripts/config.env read from it.
• Don't hand-run codesign/notarytool — macos sign/macos release sequence them correctly (inside-out signing, hardened runtime, staple, verify).
• A release isn't done until the appcast has a signed item and the enclosure URL returns 200.
• For architecture/app-shape decisions, read ~/blueprints/macos/skills/macos-blueprint/SKILL.md.