macctl

A small Bun CLI for controlling a Mac from the terminal. Commands print structured JSON so scripts and tools can parse results reliably.

Agents and voice workflows: This is a good fit for locally running agents (or voice assistants in “tool use” mode) that need safe, explicit control of a MacBook—e.g. adjusting volume or locking the screen—without opening full GUI automation for every action.

Requirements

• macOS
• Bun installed

Installation

npm install -g macctl
# or
bun install -g macctl

Development

Clone and install:

git clone https://github.com/serverdaun/macctl.git
cd macctl
bun install

Run from source:

bun run dev -- --help

Install globally from source:

bun link

Commands

Volume

Command	Description
macctl volume get	Current output volume and mute state
macctl volume set <0-100>	Set volume
macctl volume up [amount]	Increase (default +5)
macctl volume down [amount]	Decrease (default −5)
macctl volume mute <state>	state: on, off, or toggle

Screen

Command	Description
macctl screen lock	Lock the screen

App

Command	Description
macctl app open <name>	Open an application
macctl app focus <name>	Bring an application to the foreground
macctl app quit <name>	Quit an application gracefully
macctl app running <name>	Check whether an application is running
macctl app list	List visible running applications

Output

Successful runs emit JSON with status, action, message, and optional data. Example:

macctl volume get

{ "status": "success", "action": "volume.get", "message": "Volume is 42", "data": { "outputVolume": 42, "outputMuted": false } }

Dev scripts

bun run build      # bundle to dist/
bun run start      # run built CLI
bun run check      # format + lint (Biome)
bun run check:fix  # auto-fix lint/format issues
bun run release:patch  # bump patch version, validate, commit, and tag

Releasing

Create a patch release from a clean main branch:

bun run release:patch
git push origin main --follow-tags