Subcommand reference

This page lists every macli <subcmd> function, its options, and the meaning of every output field.

Output conventions

Form	Command	Default	With `--tsv`
Snapshot	`smc`, `battery`, `ssd`, `gpu`, `display`, `cal`, `event`, `reminder`, `aka`	JSON	TSV
Streaming	`monitor`	TSV only	—

All snapshot commands return a top-level envelope:

{
  "ok": true,
  "source": "HID",
  ...
}

On failure:

{
  "ok": false,
  "error": "...",
  "hint": "..."
}

Commands never fail silently.

Command tree

macli
├── smc      # Apple Silicon SMC sensors (HID)
│   ├── temp
│   ├── volt
│   ├── curr
│   ├── power
│   ├── batt
│   ├── fans
│   └── all
├── smc86    # Intel SMC sensors (legacy)
│   ├── temp
│   ├── volt
│   ├── curr
│   ├── power
│   ├── batt
│   ├── fans
│   └── all
├── battery  # Battery health and power telemetry
├── ssd      # NVMe / SSD info from system_profiler
├── gpu
│   └── info # GPU name, cores, unified memory
├── display
│   ├── list       # list online displays
│   └── brightness # read or set brightness
├── monitor  # streaming TSV monitor
├── cal      # calendars
│   ├── ls
│   ├── la
│   ├── add
│   └── rm
├── event    # calendar events
│   ├── ls
│   ├── show
│   ├── add
│   ├── edit
│   └── rm
├── reminder # reminders
│   ├── ls
│   ├── show
│   ├── add
│   ├── rm
│   ├── complete
│   └── undo
└── aka      # calendar / list aliases
    ├── ls
    ├── set
    └── rm

SMC sensors

macli smc reads hardware sensors on Apple Silicon (M1/M2/M3/M4/M5) through the HID sensor hub. macli smc86 is the Intel-Mac counterpart; it returns empty or an error on Apple Silicon because Apple cleared the Intel SMC key space.

`macli smc temp`

Temperature sensors reported by the Apple Silicon HID thermal sensor hub.

macli smc temp        # JSON
macli smc temp --tsv  # TSV

JSON output:

Field	Type	Meaning
`ok`	bool	`true` if the read succeeded
`source`	string	Always `"HID"`
`sensors`	array	Sensor objects
`sensors[].name`	string	Human-readable sensor name, e.g. `"PMU tdie1"`
`sensors[].value`	number	Temperature in degrees Celsius
`sensors[].unit`	string	Always `"°C"`
`count`	int	Number of sensors
`note`	string	Scope caveat: only HID thermal sensors are enumerated

TSV columns: name, value, unit.

`macli smc volt`

Voltage rails from the PMU.

Field	Type	Meaning
`ok`	bool	Success flag
`source`	string	`"HID"`
`sensors[].name`	string	Rail name, e.g. `"PMU vldo1"`
`sensors[].value`	number	Voltage
`sensors[].unit`	string	e.g. `"V"`
`count`	int	Sensor count

`macli smc curr`

Current sensors from the PMU.

Field	Type	Meaning
`sensors[].name`	string	Rail name, e.g. `"PMU ildo1"`
`sensors[].value`	number	Current
`sensors[].unit`	string	e.g. `"A"`

`macli smc power`

Power telemetry derived from AppleSmartBattery / adapter details.

Field	Type	Meaning
`ok`	bool	Success flag
`source`	string	`"IOKit"`
`sensors[]`	array	Power sensor objects
`sensors[].name`	string	`"Battery Power"`, `"AC Adapter Power"`
`sensors[].value`	number	Power in watts
`sensors[].unit`	string	`"W"`
`count`	int	Sensor count
`note`	string	`"No battery found; power readings unavailable"` when applicable

`macli smc batt`

Battery status via IOKit. See macli battery for the full standalone output.

`macli smc fans`

Apple Silicon Macs use passive cooling, so this returns an empty fan list with a note explaining why.

`macli smc all`

Returns everything from temp, volt, curr, power, and batt in one JSON object. In TSV mode, sections are separated by blank lines and # comments.

`macli smc86` (Intel legacy)

Same subcommands as macli smc, but reads the Intel SMC key space (keys such as TCXC, TG0P, fan IDs, etc.). Returns empty or an error on Apple Silicon. Will be removed when Intel Macs reach end-of-life.

Intel sensor objects also include a key field — the 4-character SMC key.

`macli battery`

Battery snapshot via IOKit (AppleSmartBattery). The current output is the full/detail set; a future release will add a --detail flag and default to a smaller subset, keeping the same field names.

macli battery         # JSON (default)
macli battery --tsv   # TSV
macli battery --plist # raw IORegistry XML plist

Key fields:

Field	Type	Meaning
`ok`	bool	`true` if a battery was found and read
`present`	bool	Whether a battery is present
`source`	string	`"IOKit"`
`status`	string	`"AC"` or `"Battery"`
`externalConnected`	bool	Is AC adapter plugged in
`isCharging`	bool	Is the battery currently charging
`designCapacity`	int	Design capacity in mAh
`maxCapacity`	int	Maximum capacity in mAh
`currentCapacity`	int	Current charge in mAh
`nominalChargeCapacity`	int	Nominal charge capacity in mAh
`healthPercent`	number	`maxCapacity / designCapacity * 100`
`voltage`	int	Pack voltage in mV
`amperage`	int	Average amperage in mA
`instantAmperage`	int	Instant amperage in mA
`temperature`	number	Pack temperature in °C
`cycleCount`	int	Charge cycle count
`serialNumber`	string	System-level battery serial
`batterySerial`	string	Gas-gauge battery serial
`adapter`	object	Adapter details (`watts`, `current`, `adapterVoltage`, …)
`charger`	object	Charger details (`voltage`, `current`, `powerWatts`, `notChargingReason`, …)
`systemPower`	number	System power draw in W
`instantPowerWatts`	number	Instant battery power in W
`cellVoltageDelta`	number	Max - min cell voltage in V
`raTableRaw`	[[int]]	Per-cell resistance table decoded from binary
`batteryStateBytes`	[int]	Gas-gauge status bytes
`mfgDataAscii`	string	Printable ASCII extracted from `MfgData`

The full field reference, diagnostics cookbook, binary blob decoding notes, and why serialNumber/batterySerial may differ — is in battery.md.

Scripting example — alert when battery health drops below 80%:

macli battery | jq -e '.healthPercent < 80' && echo "consider replacement"

`macli ssd`

SSD / NVMe drive info and SMART status from system_profiler SPNVMeDataType.

macli ssd

JSON output:

Field	Type	Meaning
`ok`	bool	Success flag
`source`	string	`"system_profiler"`
`controllers`	array	One entry per NVMe controller
`controllers[].name`	string	Controller name
`controllers[].drives[]`	array	Drives under this controller
`drives[].name`	string	Drive name
`drives[].model`	string	Device model
`drives[].serial`	string	Serial number
`drives[].revision`	string	Firmware revision
`drives[].bsdName`	string	e.g. `disk0`
`drives[].size`	string	Human-readable size
`drives[].sizeInBytes`	int	Size in bytes
`drives[].smartStatus`	string	SMART status string
`drives[].trimSupport`	string	TRIM support status
`drives[].removable`	string	Removable media flag
`drives[].volumes[]`	array	Volumes on this drive
`volumes[].name`	string	Volume name
`volumes[].bsdName`	string	Volume BSD name
`volumes[].size`	string	Human-readable size
`volumes[].sizeInBytes`	int	Volume size in bytes
`volumes[].content`	string	Content type
`note`	string	Notes about SMART scope

macOS does not expose detailed SMART log pages (wear percentage, TBW, media errors) through a public API. For that data, use smartctl:

brew install smartmontools
smartctl -a disk0

`macli gpu info`

GPU information via Metal and AGXAccelerator in IOKit.

macli gpu info        # JSON
macli gpu info --tsv  # TSV

Field	Type	Meaning
`ok`	bool	Success flag
`source`	string	`"Metal/IOKit"`
`name`	string	GPU name, e.g. `"Apple M3 Pro"`
`hasUnifiedMemory`	bool	Whether CPU and GPU share memory
`recommendedMaxWorkingSetSizeBytes`	int	Recommended max GPU memory in bytes
`coreCount`	int	GPU core count (Apple Silicon)

`macli display`

Display brightness and info via the private DisplayServices framework.

`macli display list`

List online displays.

macli display list        # JSON
macli display list --tsv  # TSV

Field	Type	Meaning
`ok`	bool	Success flag
`source`	string	`"DisplayServices"`
`displays[]`	array	Online displays
`displays[].id`	int	Display ID in hex (e.g. `0x1`)
`displays[].main`	bool	Is the main display
`displays[].builtIn`	bool	Is the built-in display
`displays[].active`	bool	Is currently active
`displays[].brightness`	number	Brightness level `0.0–1.0` if readable

`macli display brightness`

Read or set built-in display brightness.

macli display brightness             # read
macli display brightness --set 0.5   # set to 50%

When reading, the schema is the same as display list. When setting, the output is:

Field	Type	Meaning
`ok`	bool	Success flag
`displayID`	int	Affected display ID
`brightness`	number	Clamped brightness `0.0–1.0`
`error`	string	Present on failure

`macli monitor`

Streaming TSV monitor. Single process, all metric sources, downstream awk-friendly.

macli monitor
macli monitor --interval 1 --metric smc_temp,smc_curr
macli monitor --count 10 --interval 0.5

Flags:

Flag	Type	Default	Meaning
`--interval`	number	`1.0`	Seconds between samples (decimals allowed)
`--metric`	string	all	Comma-separated source or column-prefix filters. `--metrics` is accepted as a legacy alias.
`--count`	int	infinite	Exit after N samples

Available metric sources:

Source	Data
`smc_temp`	HID temperature sensors
`smc_volt`	HID voltage sensors
`smc_curr`	HID current sensors
`battery_power`	Battery / AC adapter power in W
`gpu_metrics`	GPU utilization (experimental, Apple Silicon only)

Output is TSV. The first line is the header; each subsequent line starts with a Unix timestamp followed by metric values. Column order is locked by the header.

ts        smc_temp_PMU_tdie1  smc_temp_PMU_tdie2  battery_power_Battery_Power
1718812800.000  57.5                48.0                8.2

Why this matters: a shell loop (while; do macli smc temp; sleep 1; done) costs ~50 ms of binary startup per iteration. monitor pays that once and streams samples at sub-millisecond marginal cost.

`macli cal`

Calendar management via EventKit.framework.

macOS will prompt for Calendar access the first time you run a cal / event command. Grant it in the system dialog. If you miss the prompt, go to System Settings → Privacy & Security → Calendars.

`macli cal ls`

List event calendars.

macli cal ls

Field	Type	Meaning
`calendars[]`	array	Event calendars
`calendars[].uid`	string	Stable calendar identifier
`calendars[].name`	string	Calendar title
`calendars[].kind`	string	`"event"`
`calendars[].src`	string	Account source, e.g. `"iCloud"`
`calendars[].color`	string	Hex color, e.g. `"#FF0000"`
`calendars[].canEdit`	bool	Can content be modified
`calendars[].calType`	string	`local`, `caldav`, `exchange`, `subscription`, `birthday`, `unknown`
`calendars[].isSubscribed`	bool	Is a subscribed calendar
`calendars[].isImmutable`	bool	Is read-only / immutable

`macli cal la`

List all calendars, including reminder lists.

`macli cal add`

Create a new calendar or reminder list.

macli cal add --name Work --color #FF0000
macli cal add --name Shopping --type reminder

Flag	Required	Default	Meaning
`--name`	yes	—	Calendar title
`--type`	no	`event`	`event` or `reminder`
`--color`	no	—	Hex color

Output: the created calendar object.

`macli cal rm`

Delete a calendar or reminder list. Requires --yes.

macli cal rm <calendar-id> --yes
macli cal rm <list-id> --type reminder --yes

Flag	Required	Default	Meaning
`--type`	no	`event`	`event` or `reminder`
`--yes`	yes	—	Confirm destructive deletion

Output: {"deletedCalendarId": "..."}

`macli event`

Calendar event management.

`macli event ls`

List events in a date range.

macli event ls --calendar work --today
macli event ls --calendar work --week
macli event ls --calendar work --from 2024-01-01 --to 2024-01-31

Flag	Required	Meaning
`--calendar`	yes	Calendar ID or alias
`--from`	*	Start date (ISO8601 or `today`/`tomorrow`/`+7`)
`--to`	*	End date
`--today`	*	Today’s events
`--week`	*	This week’s events
`--month`	*	This month’s events

* Either --today / --week / --month or both --from and --to are required.

Output fields:

Field	Type	Meaning
`events[]`	array	Matching events
`events[].uid`	string	Event identifier
`events[].title`	string	Event title
`events[].cal.uid`	string	Calendar ID
`events[].cal.name`	string	Calendar name
`events[].isAllDay`	bool	All-day event
`events[].start`	string	ISO8601 start date
`events[].end`	string	ISO8601 end date
`events[].loc`	string	Location
`events[].note`	string	Notes
`events[].link`	string	URL
`events[].hasAlarm`	bool	Has an alarm
`events[].hasRepeat`	bool	Is repeating
`count`	int	Number of events

`macli event show <id>`

Show a single event by ID.

`macli event add`

Create an event.

macli event add --calendar work --title Meeting \
  --start 2024-01-15T10:00 --end 2024-01-15T11:00 \
  --location "Room A" --notes "Weekly sync" --alarm 15

Flag	Required	Meaning
`--calendar`	yes	Calendar ID or alias
`--title`	yes	Event title
`--start`	yes	Start date/time
`--end`	yes	End date/time
`--location`	no	Location
`--notes`	no	Notes
`--all-day`	no	All-day event
`--alarm`	no	Alarm minutes before start

`macli event edit <id>`

Update an event.

macli event edit <id> --title "New title" --start 2024-01-15T11:00

`macli event rm <id> --yes`

Delete an event.

`macli reminder`

Reminder management.

macOS will prompt for Reminders access the first time you run a reminder command. Grant it in the system dialog. If you miss the prompt, go to System Settings → Privacy & Security → Reminders.

`macli reminder ls`

List reminders in a list.

macli reminder ls --list work
macli reminder ls --list work --completed true

Flag	Required	Meaning
`--list`	yes	List ID or alias
`--completed`	no	Filter by `true` or `false`

Output fields:

Field	Type	Meaning
`reminders[]`	array	Matching reminders
`reminders[].uid`	string	Reminder identifier
`reminders[].title`	string	Title
`reminders[].list.uid`	string	List ID
`reminders[].list.name`	string	List name
`reminders[].isDone`	bool	Completed
`reminders[].doneAt`	string	Completion date ISO8601
`reminders[].due`	string	Due date ISO8601
`reminders[].note`	string	Notes
`reminders[].link`	string	URL
`reminders[].prio`	int	Priority
`count`	int	Number of reminders

`macli reminder show <id>`

Show a single reminder.

`macli reminder add`

Create a reminder.

macli reminder add --list work --title "Buy milk" --due 2024-01-15

Flag	Required	Meaning
`--list`	yes	List ID or alias
`--title`	yes	Title
`--due`	no	Due date/time
`--priority`	no	Priority integer
`--notes`	no	Notes

`macli reminder rm <id> --yes`

Delete a reminder.

`macli reminder complete <id>`

Mark a reminder as complete.

`macli reminder undo <id>`

Undo completion of a reminder.

`macli aka`

Manage aliases for calendar and reminder list IDs. Calendar IDs are UUIDs that can change across devices or Apple ID migrations; aliases give you stable references in scripts.

`macli aka ls`

List all aliases.

{
  "aka": [
    {"name": "work", "id": "..."},
    {"name": "home", "id": "..."}
  ],
  "count": 2,
  "configPath": "..."
}

`macli aka set <name> <id>`

Set an alias.

macli aka set work <calendar-id>

`macli aka rm <name>`

Remove an alias.

macli aka rm work

Subcommand reference

Output conventions

Command tree

SMC sensors

macli smc temp

macli smc volt

macli smc curr

macli smc power

macli smc batt

macli smc fans

macli smc all

macli smc86 (Intel legacy)

macli battery

macli ssd

macli gpu info

macli display

macli display list

macli display brightness

macli monitor

macli cal

macli cal ls

macli cal la

macli cal add

macli cal rm

macli event

macli event ls

macli event show <id>

macli event add

macli event edit <id>

macli event rm <id> --yes

macli reminder

macli reminder ls

macli reminder show <id>

macli reminder add

macli reminder rm <id> --yes

macli reminder complete <id>

macli reminder undo <id>

macli aka

macli aka ls

macli aka set <name> <id>

macli aka rm <name>