ApexDock is fully scriptable. Whatever you can do in the GUI, you can do from a shell, AppleScript, Shortcuts.app, Raycast, Alfred, Keyboard Maestro, or any other host that can hit a Unix socket or open a URL.
Pick your transport
| Want to... | Use |
|---|---|
| Drive ApexDock from a shell script | CLI (apexdock workspace switch Work) |
| Drive ApexDock from Shortcuts.app or a browser | URL scheme (apexdock://workspace/switch?name=Work) |
| Drive ApexDock from AppleScript / JXA | AppleScript dictionary |
| Push live state into the bar (CPU monitor, build status) | Widget wire (Unix socket, NDJSON) |
| Surface CLI agent activity (Claude Code / Codex / custom tools) | Hook API (Unix socket + file drop) |
| Build a declarative widget driven by a shell command | Widget YAML |
All sockets live in ~/Library/Application Support/ApexDock/api/ with 700 parent and 600 socket permissions — only the owning user can connect.
Three socket APIs
~/Library/Application Support/ApexDock/api/
├── control.sock ← Control API (workspace.switch, app.focus, palette.show, ...)
├── api.sock ← Hook API (agent session events + bidirectional approvals)
└── widgets.sock ← Widget wire (push tray cells, per-connection ownership)
Each speaks NDJSON — one JSON object per line, request/response or event-stream, depending on the verb.
Versioning
Every wire schema carries v: 1. Future breaking changes will bump to v: 2 and reject v: 1 events with a logged warning. Current verbs and shapes are stable for v: 1.
Authorisation model
There is no token. Auth is filesystem permissions. The parent dir is 700 (owner-only), the sockets are 600 (owner read/write). Any process running under your user can connect.
If you're concerned about other apps under the same user impersonating you, you should run them under a different user account — the OS doesn't make finer-grained distinctions for AF_UNIX sockets.
Where API surfaces map back to features
| API verb | Feature page |
|---|---|
workspace.* | Workspaces |
app.focus, app.list-pinned | Pinned & Running Apps |
bar.*, action.* | Concepts → The bar |
settings.open | Settings reference |
palette.* | Command Palette |
| Widget wire frames | Widgets overview |
| Hook events | Agents |
What's in this section
- Control API — verbs, NDJSON wire, URL scheme
- Widget wire — push frames, file drop
- Hook API — agent events, approval handshake, Claude Code wiring
- AppleScript — verbs, properties, Shortcuts integration
- CLI reference — every subcommand and flag
- Licensing — activation, deactivation, refresh, offline grace