CLI reference
All commands accept --config PATH, --socket PATH, and --log-level LEVEL. --config selects the file at daemon startup; passing it to a client does not reconfigure a daemon that is already running. --socket selects the private control socket.
Run kact COMMAND --help for Clap’s argument help, for example kact click --help. Action commands require a running daemon; run kact setup first.
Service and configuration
Section titled “Service and configuration”| Command | Purpose |
|---|---|
setup |
Create configuration, guide macOS Accessibility, and start the daemon. |
uninstall [--purge] |
Remove a release-script installation; --purge also removes config, logs, and socket. |
update [--check] |
Check for or install the latest verified release-script update. |
start |
Start the background daemon; safe to repeat. |
daemon |
Run the daemon in the foreground. |
service install / uninstall |
Configure macOS login startup. |
status |
Return daemon and navigation state. |
quit |
Stop the daemon and release held buttons. |
doctor |
Check config, Accessibility, and service availability without pointer movement. |
config init |
Create the default configuration without overwriting one. |
config check |
Validate the configuration and bindings. |
config path |
Print the resolved config path. |
reload |
Reload the active daemon configuration. |
Lifecycle example
Section titled “Lifecycle example”kact setupkact statuskact stop # stops held movement; daemon remains runningkact deactivate # also hides an active overlaykact quit # stops the daemonstatus returns JSON including daemon state, pointer position when available, active navigation mode, whether held movement or a glide is active, configuration path, and enabled shortcut counts.
update is available only when the current executable is the unmodified binary installed by Kact’s release script. It reads the latest stable GitHub Release, verifies the matching archive against its published SHA-256 checksum, atomically replaces the binary, and restarts a running daemon. update --check performs only the release lookup. Update Homebrew, Cargo, and source-checkout installations with the tool that installed them.
Navigation and motion
Section titled “Navigation and motion”| Command | Syntax | Purpose |
|---|---|---|
| Activate | activate [grid|elements|freestyle] |
Start a mode; default is freestyle. |
| Refresh | refresh |
Rescan active element navigation. |
| Filter elements | filter QUERY |
Relabel active element targets matching accessible title, description, value, help text, or role. |
| Next / previous target | next / previous |
Move the cursor and selection through active element targets. |
| Toggle | toggle [grid|elements|freestyle] |
Activate the mode or deactivate an active mode. |
| Deactivate | deactivate |
Hide navigation and release held input. |
| Cancel | cancel |
Clear a label prefix or deactivate if empty. |
| Move | move --dx N --dy N [--glide] |
Move by relative points, optionally animating to the resolved endpoint. |
| Move absolute | move-to --x N --y N [--glide] |
Move to global coordinates, optionally animating to the endpoint. |
| Start motion | move-start <up|down|left|right> [--speed normal|precise|fast] |
Begin continuous movement, with an optional held speed override. |
| Stop motion direction | move-stop <direction> |
Stop one continuous direction. |
| Speed | speed <normal|precise|fast> |
Select motion multiplier. |
| Stop | stop |
Stop movement and release every held button. |
| Jump | jump <top|bottom|left|right|center|cycle> |
Move to display edge, center, or cycle corners. |
Coordinates must be finite and within ±1,000,000. A glide captures its start and target when received, reaches that target exactly, and never queues. A new pointer action, move-start, stop, deactivation, reload, or quit cancels it. Continuous commands require a running daemon and should be paired in order.
activate grid shows labeled cells on every display. activate elements labels visible, enabled actionable accessibility targets in the focused macOS window and falls back to a grid when no targets are available. Its first activation scans the focused window; repeating it for that same active window preserves existing labels. Use refresh to scan again when the initial result is incomplete or the UI changes. filter, next, and previous also require an active elements overlay. filter limits labels to matching accessibility metadata; next and previous cycle its targets. activate freestyle enables local movement controls without showing an overlay. toggle MODE deactivates any active mode, regardless of the requested mode.
inspect elements reports action-aware element discovery diagnostics without printing accessible text. Use inspect elements --pid PID to inspect an application without focusing it first; --show-text includes accessible text only when it is safe to expose in terminal history. --save-baseline FILE writes source, role, and geometry only; --diff-baseline FILE reports added and removed targets from a later scan. An empty result or titlebar-only targets means the app did not expose usable Accessibility controls; element mode then falls back to grid.
Pointer and labels
Section titled “Pointer and labels”| Command | Syntax | Purpose |
|---|---|---|
| Click | click [--button left|right|middle] [--count 1..3] [--modifiers cmd,shift] |
Click at the cursor. |
| Hold | button-down [--button …] [--modifiers …] |
Start a drag. |
| Release | button-up [--button …] [--modifiers …] |
End a drag. |
| Scroll | scroll --dx N --dy N |
Positive dy scrolls up; positive dx scrolls left. |
| Select | select LABEL |
Enter an active target label. |
| Backspace | backspace |
Remove one label character. |
| Refine | refine |
Subdivide the most recently selected grid cell. |
| Presentation | show <grid-lines|labels|larger|smaller|more-contrast|less-contrast> |
Change active overlay presentation. |
Label values must be 1–64 ASCII characters. Scroll inputs are limited to ±100,000 by the CLI; X11 additionally limits them to 1,000 wheel steps. Modified clicks are macOS-only.
Pointer examples
Section titled “Pointer examples”# Right-click, double-click, and Cmd-click.kact click --button rightkact click --count 2kact click --modifiers cmd
# Drag, then release it. `stop` can recover a held button.kact button-down --button leftkact move --dx 160 --dy 40kact button-up --button left
# Select a displayed target through the command interface.kact activate gridkact select aashow changes the current overlay session only: it does not write configuration. show larger and show smaller change grid density; contrast, label visibility, and grid lines reset at the next activation.