# Macos

> 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.

- Skill: `iannuttall/macos` (Agent Skill)
- Install (CLI): `npx skillmds@latest add iannuttall/macos`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iannuttall/macos/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: iannuttall (https://skillmd.com/u/iannuttall)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/iannuttall/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`.