System Actions

Overview

System actions control macOS settings, apps, volume, dark mode, battery info, Wi-Fi, clipboard, and more.

Category	Actions
App Control	`open_app`, `quit_app`, `open_url`, `list_apps`, `get_frontmost_app`
Window Management	`close_window`, `minimize_window`, `fullscreen_window`
System Settings	`set_volume`, `toggle_dark_mode`, `lock_screen`, `screenshot`, `open_settings`
System Info	`get_battery`, `get_wifi`, `get_ip_address`, `get_uptime`, `get_disk_usage`
Files & Clipboard	`search_files`, `clipboard_read`, `clipboard_write`

App Control

open_app

Open an application or website. Automatically detects URLs and uses the appropriate handler.

app

string

required

Application name (e.g., “Safari”) or website URL (e.g., “github.com”)

rcli listen
# Say: "Open Safari"
# Say: "Open github.com"

Implementation (src/actions/app_control_actions.cpp:16-33)

Detects URLs by checking for :// or common TLDs (.com, .org, .io, etc.):

if (looks_like_url(app)) {
    std::string url = app;
    if (url.find("://") == std::string::npos) url = "https://" + url;
    run_shell("open '" + escape_shell(url) + "'");
} else {
    run_shell("open -a '" + escape_shell(app) + "'");
}

Source: src/actions/app_control_actions.cpp:16-33

quit_app

Quit a macOS application.

app

string

required

Application name (e.g., “Safari”)

rcli listen
# Say: "Quit Safari"

Implementation (src/actions/app_control_actions.cpp:59-65)

tell application "<app>" to quit

Source: src/actions/app_control_actions.cpp:59-65

open_url

Open a URL in the default browser. Similar to open_app but explicitly for URLs.

url

string

required

URL to open (auto-prepends https:// if missing)

rcli ask "go to github.com"
rcli action open_url '{"url": "https://github.com"}'

list_apps

List all currently running applications.

rcli listen
# Say: "What apps are running?"

Implementation (src/actions/app_control_actions.cpp:46-56)

tell application "System Events"
  set appNames to name of every application process whose visible is true
  set AppleScript's text item delimiters to ", "
  return appNames as text
end tell

Source: src/actions/app_control_actions.cpp:46-56

get_frontmost_app

Get the name of the currently active application.

rcli listen
# Say: "What app am I using?"

Window Management

close_window

Close the frontmost window (Cmd+W).

rcli listen
# Say: "Close this window"

minimize_window

Minimize the frontmost window (Cmd+M).

rcli listen
# Say: "Minimize this window"

fullscreen_window

Toggle fullscreen for the frontmost window (Ctrl+Cmd+F).

rcli listen
# Say: "Make this fullscreen"

System Settings

set_volume

Set system volume (0-100).

level

string

required

Volume level from 0 to 100

rcli listen
# Say: "Set the volume to 50 percent"
# Say: "Turn the volume down to 20"

Implementation (src/actions/system_actions.cpp:19-28)

set volume output volume <level>

Source: src/actions/system_actions.cpp:19-28

toggle_dark_mode

Toggle between light and dark appearance.

rcli listen
# Say: "Turn on dark mode"
# Say: "Toggle dark mode"

Implementation (src/actions/system_actions.cpp:30-36)

tell application "System Events" to tell appearance preferences
  set dark mode to not dark mode
end tell

Source: src/actions/system_actions.cpp:30-36

lock_screen

Lock the screen immediately.

rcli listen
# Say: "Lock my screen"

Implementation (src/actions/system_actions.cpp:38-45)

Tries pmset displaysleepnow first, then falls back to Cmd+Ctrl+Q keystroke:

run_shell("pmset displaysleepnow");
// Fallback:
run_applescript(
  "tell application \"System Events\" to keystroke \"q\" using {control down, command down}"
);

Source: src/actions/system_actions.cpp:38-45

screenshot

Take a screenshot and save to a file.

path

string

default:"/tmp/rcli_screenshot.png"

Save path (defaults to /tmp/rcli_screenshot.png)

rcli listen
# Say: "Take a screenshot"

Implementation (src/actions/system_actions.cpp:9-17)

screencapture -x '<path>'

Source: src/actions/system_actions.cpp:9-17

open_settings

Open System Settings, optionally to a specific pane.

pane

string

Pane name: wifi, bluetooth, sound, display, battery, keyboard, privacy, notifications, general, appearance, etc. (see full list in source)

rcli listen
# Say: "Open Wi-Fi settings"
# Say: "Open System Settings"

Supported Panes (src/actions/system_actions.cpp:70-108)

The action maps common names to macOS System Settings pane IDs:

wifi, bluetooth, network, sound, display, battery
keyboard, trackpad, mouse, printers
privacy, security, notifications, focus
general, appearance, accessibility, storage
siri, spotlight, passwords, users, icloud
desktop, dock, time machine, sharing, vpn
And more…

Source: src/actions/system_actions.cpp:70-135

System Info

get_battery

Get battery percentage and charging status.

rcli listen
# Say: "What's my battery level?"
# Say: "Check battery"

Implementation (src/actions/system_actions.cpp:47-58)

pmset -g batt | grep -Eo '[0-9]+%' | head -1  # Get percentage
pmset -g batt | grep -o 'charging\|discharging\|charged\|AC Power'  # Get status

Response:

{
  "action": "get_battery",
  "percent": "87%",
  "status": "discharging"
}

Source: src/actions/system_actions.cpp:47-58

get_wifi

Get the current Wi-Fi network name.

rcli listen
# Say: "What Wi-Fi am I connected to?"

Implementation (src/actions/system_actions.cpp:60-68)

networksetup -getairportnetwork en0 | sed 's/Current Wi-Fi Network: //'

Source: src/actions/system_actions.cpp:60-68

get_ip_address

Show local and public IP addresses.

rcli listen
# Say: "What's my IP address?"

Implementation (src/actions/system_actions.cpp:153-161)

ipconfig getifaddr en0  # Local IP
curl -s --max-time 5 ifconfig.me  # Public IP

Response:

{
  "action": "get_ip_address",
  "local": "192.168.1.42",
  "public": "203.0.113.45"
}

Source: src/actions/system_actions.cpp:153-161

get_uptime

Show how long the system has been running.

rcli listen
# Say: "How long has my Mac been running?"

get_disk_usage

Show disk space usage.

rcli listen
# Say: "How much disk space do I have?"

Implementation (src/actions/system_actions.cpp:137-143)

df -h / | tail -1 | awk '{print "Total: " $2 ", Used: " $3 ", Available: " $4 ", Capacity: " $5}'

Example Response:

Total: 500GB, Used: 320GB, Available: 180GB, Capacity: 64%

Source: src/actions/system_actions.cpp:137-143

Files & Clipboard

search_files

Search for files using Spotlight (mdfind).

query

string

required

Search term

rcli listen
# Say: "Find files about project plan"

Implementation (src/actions/files_actions.cpp:7-17)

mdfind '<query>' | head -20

Timeout: 15 secondsSource: src/actions/files_actions.cpp:7-17

clipboard_read

Read text from the clipboard.

rcli listen
# Say: "What's on my clipboard?"

Implementation (src/actions/clipboard_actions.cpp:7-12)

pbpaste

Source: src/actions/clipboard_actions.cpp:7-12

clipboard_write

Copy text to the clipboard.

text

string

required

Text to copy

rcli listen
# Say: "Copy 'Hello World' to my clipboard"

Implementation (src/actions/clipboard_actions.cpp:14-20)

printf '%s' '<text>' | pbcopy

Source: src/actions/clipboard_actions.cpp:14-20

search_web

Search the web using Google, DuckDuckGo, or Bing.

query

string

required

Search query

engine

string

default:"google"

Search engine: google, duckduckgo, or bing

rcli listen
# Say: "Google how to make sourdough bread"
# Say: "Search DuckDuckGo for privacy tools"

search_youtube

Search YouTube for videos.

query

string

required

Search query

rcli listen
# Say: "Search YouTube for guitar tutorials"

get_browser_url

Get the URL of the active browser tab (Safari, Chrome, or Arc).

rcli listen
# Say: "What page am I looking at?"

get_browser_tabs

List all open browser tabs in the front window.

rcli listen
# Say: "Show my open tabs"

open_maps

Search for a place or address in Apple Maps.

query

string

required

Place or address to search

rcli listen
# Say: "Show me coffee shops nearby"

Managing These Actions

See Managing Actions for details on enabling/disabling actions and persisting preferences.

# List all system actions
rcli actions | grep system

# Enable screenshot
rcli action screenshot --enable

# Disable clipboard_read
rcli action clipboard_read --disable

Get Started

Core Features

Commands

Models

Actions

Advanced

Development

​Overview

​App Control

​open_app

​quit_app

​open_url

​list_apps

​get_frontmost_app

​Window Management

​close_window

​minimize_window

​fullscreen_window

​System Settings

​set_volume

​toggle_dark_mode

​lock_screen

​screenshot

​open_settings

​System Info

​get_battery

​get_wifi

​get_ip_address

​get_uptime

​get_disk_usage

​Files & Clipboard

​search_files

​clipboard_read

​clipboard_write

​Web & Navigation

​search_web

​search_youtube

​get_browser_url

​get_browser_tabs

​open_maps

​Managing These Actions

Build docs developers (and LLMs) love

Overview

App Control

open_app

quit_app

open_url

list_apps

get_frontmost_app

Window Management

close_window

minimize_window

fullscreen_window

System Settings

set_volume

toggle_dark_mode

lock_screen

screenshot

open_settings

System Info

get_battery

get_wifi

get_ip_address

get_uptime

get_disk_usage

Files & Clipboard

search_files

clipboard_read

clipboard_write

Web & Navigation

search_web

search_youtube

get_browser_url

get_browser_tabs

open_maps

Managing These Actions