npm install -g @unlikeotherai/kelpie
# or
pnpm add -g @unlikeotherai/kelpiekelpie <command> [options]
| Flag | Description |
|---|---|
--device <id|name|ip> |
Target a specific device by ID (most reliable), name, or IP |
--format <type> |
Output format: json (default), table, text |
--timeout <ms> |
CLI-level command timeout in milliseconds (default: 10000). Overrides per-method API defaults (typically 5000ms). |
--port <port> |
Override default port 8420 |
--help |
Show help for any command |
--version |
Show CLI version |
--llm-help |
Show detailed LLM-oriented help with schemas and examples |
Scan the local network for Kelpie browser instances.
kelpie discover
kelpie discover --timeout 5000 # custom scan durationOutput:
{
"devices": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "My iPhone",
"ip": "192.168.1.42",
"port": 8420,
"platform": "ios",
"model": "iPhone 15 Pro",
"resolution": "390x844",
"version": "1.0.0"
}
],
"count": 1
}Alias: kelpie devices is equivalent to kelpie discover.
Check if a device is reachable. Without --device, pings all known devices.
kelpie ping --device "My iPhone"
kelpie ping # ping allManage local macOS Kelpie app aliases stored in ~/.kelpie/browsers.json.
kelpie browser --helpRegister or update a named local macOS browser alias.
kelpie browser register claude-a
kelpie browser register codex-b --app /Applications/Kelpie.appLaunch a new local macOS Kelpie app instance for a registered alias. If --port is omitted, the CLI auto-selects the first safe free port and skips reserved ports such as 8421 used by AppReveal and CLI MCP.
kelpie browser launch claude-a
kelpie browser launch codex-b --port 8450 --waitList registered local browser aliases and their saved runtime state.
kelpie browser listShow the saved app path, runtime port, and reachability for one alias.
kelpie browser inspect claude-aRemove a saved local alias and its runtime state. This does not terminate a running app process.
kelpie browser remove claude-akelpie navigate "https://example.com" --device "My iPhone"kelpie back --device "My iPhone"
kelpie forward --device "My iPhone"
kelpie reload --device "My iPhone"Get current URL and title.
kelpie url --device "My iPhone"Set the device's home page. Persisted across app restarts.
kelpie home set "https://example.com" --device "My iPhone"Get the current home page URL.
kelpie home get --device "My iPhone"kelpie screenshot --device "My iPhone"
kelpie screenshot --device "My iPhone" --output ./shot.png
kelpie screenshot --device "My iPhone" --full-page
kelpie screenshot --device "My iPhone" --base64 # return raw base64 instead of savingDefault behavior: saves to file, returns the path. Without --output, the CLI auto-generates a filename in the current directory using the pattern {device}-{timestamp}.png (e.g., my-iphone-2026-03-30T10-15-32.png). The JSON response contains the file path — never base64 — so LLMs don't waste tokens on image data.
For LLM and MCP use, prefer viewport/CSS-pixel screenshots unless you explicitly need native renderer detail. The HTTP API now includes viewport mapping metadata (viewportWidth, viewportHeight, devicePixelRatio, imageScaleX, imageScaleY) so image coordinates can be converted back into tap coordinates when needed.
| Flag | Behavior |
|---|---|
| (no flag) | Auto-save to ./{device}-{timestamp}.png, return {"file": "..."} |
--output <path> |
Save to explicit path, return {"file": "..."} |
--output <dir>/ |
Save to directory with auto-generated filename |
--base64 |
Return raw base64 JSON (for programmatic use, not LLM conversations) |
Group screenshots (kelpie group screenshot) always save to files — one per device. Use --output <dir>/ to collect them in a folder.
Get the DOM tree.
kelpie dom --device "My iPhone"
kelpie dom --device "My iPhone" --selector "main" --depth 3Query for elements.
kelpie query "#submit-btn" --device "My iPhone"
kelpie query "a.nav-link" --device "My iPhone" --allGet text content of an element.
kelpie text "h1" --device "My iPhone"Get all attributes of an element.
kelpie attributes "#email-input" --device "My iPhone"Prefer semantic interaction over raw coordinates:
- Use
kelpie a11y,kelpie find-element,kelpie find-button, orkelpie find-inputto locate the target. - Use
kelpie clickorkelpie fillwith the returned selector. - If you already know the selector but want visual confirmation, use
kelpie highlight showand thenkelpie screenshotorkelpie annotate. - If semantic targeting fails, use
kelpie annotatepluskelpie click-annotation/kelpie fill-annotation. - Use
kelpie taponly when the semantic and annotated flows are not enough.
kelpie click "#submit-btn" --device "My iPhone"kelpie tap 195 420 --device "My iPhone"Use this only as a fallback. Coordinates are sensitive to viewport changes, scrolling, and overlays.
kelpie fill "#email" "user@example.com" --device "My iPhone"kelpie type "search query" --device "My iPhone"
kelpie type "search query" --device "My iPhone" --selector "#search-box"
kelpie type "search query" --device "My iPhone" --delay 50kelpie select "#country" "us" --device "My iPhone"kelpie check "#agree-terms" --device "My iPhone"kelpie swipe 200 700 200 200 --device "My iPhone" --duration 500 --color "#3B82F6"kelpie commentary show "Watch this button" --device "My iPhone" --position bottom --duration 0
kelpie commentary hide --device "My iPhone"kelpie highlight show "#signup" --device "My iPhone" --animation draw --color "#EF4444"
kelpie highlight hide --device "My iPhone"Use --duration 0 if you want the highlight to stay visible while you capture a screenshot and ask an LLM to reason over the image using that box/ring as the visual anchor.
kelpie script run ./demo-script.json --device "My iPhone"kelpie script status --device "My iPhone"kelpie script abort --device "My iPhone"kelpie scroll --device "My iPhone" --y 500
kelpie scroll --device "My iPhone" --x 200 --y 0Resolution-aware scroll to element.
kelpie scroll2 "#footer" --device "My iPhone"
kelpie scroll2 "#footer" --device "My iPhone" --position centerkelpie scroll-top --device "My iPhone"
kelpie scroll-bottom --device "My iPhone"Get console messages from the page.
kelpie console --device "My iPhone"
kelpie console --device "My iPhone" --level error # errors only
kelpie console --device "My iPhone" --level warn # warnings only
kelpie console --device "My iPhone" --limit 50Get JavaScript errors (shorthand for console --level error).
kelpie errors --device "My iPhone"Get the network activity log — all resources loaded by the page.
kelpie network --device "My iPhone"
kelpie network --device "My iPhone" --type script # only JS files
kelpie network --device "My iPhone" --type fetch # only XHR/fetch
kelpie network --device "My iPhone" --status error # only failed requestsGet the resource loading timeline with timing data.
kelpie timeline --device "My iPhone"Clear the console message buffer.
kelpie clear-console --device "My iPhone"Watch and get DOM mutations.
kelpie mutations watch --device "My iPhone" # start watching
kelpie mutations watch --device "My iPhone" --selector "main" # scoped
kelpie mutations get --device "My iPhone" # get accumulated mutations
kelpie mutations stop --device "My iPhone" # stop watchingManage request interception rules.
kelpie intercept block "*.doubleclick.net/*" --device "My iPhone"
kelpie intercept mock "https://api.example.com/data" --body '{"items":[]}' --device "My iPhone"
kelpie intercept list --device "My iPhone"
kelpie intercept clear --device "My iPhone"Get the accessibility tree — the most LLM-friendly representation of the page.
kelpie a11y --device "My iPhone"
kelpie a11y --device "My iPhone" --interactable-only
kelpie a11y --device "My iPhone" --selector "main"Take an annotated screenshot with numbered labels on interactive elements. Same file-saving behavior as screenshot — defaults to auto-save, returns the file path.
For LLM use, prefer viewport/CSS-pixel output here too. Annotation rectangles are reported in viewport CSS pixels, not image pixels, so the index list stays stable even if the image is returned at native scale.
kelpie annotate --device "My iPhone"
kelpie annotate --device "My iPhone" --output ./annotated.png
kelpie annotate --device "My iPhone" --full-page
kelpie annotate --device "My iPhone" --base64 # raw base64 instead of fileClick an element by its annotation index from the last annotate call.
kelpie click-index 5 --device "My iPhone"This uses the same coordinate-bearing activation path as kelpie click. If the annotated target exists but is hidden or covered at its center point, the command fails instead of activating the wrong element.
Fill an element by its annotation index.
kelpie fill-index 2 "user@example.com" --device "My iPhone"Get only the elements currently visible in the viewport.
kelpie visible --device "My iPhone"
kelpie visible --device "My iPhone" --interactable-onlyExtract readable text from the page (reader mode).
kelpie page-text --device "My iPhone"
kelpie page-text --device "My iPhone" --mode markdown
kelpie page-text --device "My iPhone" --mode full
kelpie page-text --device "My iPhone" --selector "article"Get the state of all forms on the page.
kelpie form-state --device "My iPhone"
kelpie form-state --device "My iPhone" --selector "#signup-form"Check if a dialog is showing.
kelpie dialog --device "My iPhone"Handle the current dialog.
kelpie dialog accept --device "My iPhone"
kelpie dialog dismiss --device "My iPhone"
kelpie dialog accept --device "My iPhone" --prompt-text "my input"Configure automatic dialog handling.
kelpie dialog auto --action accept --device "My iPhone"
kelpie dialog auto --action dismiss --device "My iPhone"
kelpie dialog auto --action queue --device "My iPhone" # capture for later
kelpie dialog auto --off --device "My iPhone" # disableList all open tabs.
Open tabs and their current URLs are restored automatically when the browser app restarts, so kelpie tabs reflects the live restored session rather than a fresh blank state after relaunch.
kelpie tabs --device "My iPhone"Open a new tab.
kelpie tab new "https://example.com" --device "My iPhone"
kelpie tab new --device "My iPhone" # blank tabSwitch to a tab.
kelpie tab switch 1 --device "My iPhone"Close a tab.
kelpie tab close 1 --device "My iPhone"List all iframes on the page.
kelpie iframes --device "My iPhone"Switch command context into an iframe.
kelpie iframe enter 0 --device "My iPhone"
kelpie iframe enter "iframe[name='payment']" --device "My iPhone"Switch back to the main page context.
kelpie iframe exit --device "My iPhone"Check which context (main page or iframe) commands are currently targeting.
kelpie iframe context --device "My iPhone"Get cookies for the current page.
kelpie cookies --device "My iPhone"
kelpie cookies --device "My iPhone" --name "session_id"Set a cookie.
kelpie cookies set "session_id" "abc123" --device "My iPhone"
kelpie cookies set "theme" "dark" --device "My iPhone" --domain "example.com" --path "/" --secureDelete cookies.
kelpie cookies delete --name "session_id" --device "My iPhone"
kelpie cookies delete --domain "example.com" --device "My iPhone"
kelpie cookies delete --all --device "My iPhone"Read localStorage or sessionStorage.
kelpie storage --device "My iPhone" # localStorage (default)
kelpie storage --device "My iPhone" --type session
kelpie storage --device "My iPhone" --key "auth_token"Write to storage.
kelpie storage set "theme" "dark" --device "My iPhone"
kelpie storage set "theme" "dark" --device "My iPhone" --type sessionClear storage.
kelpie storage clear --device "My iPhone"
kelpie storage clear --device "My iPhone" --type session
kelpie storage clear --device "My iPhone" --type bothRead clipboard contents.
kelpie clipboard --device "My iPhone"Write to clipboard.
kelpie clipboard set "text to copy" --device "My iPhone"Override geolocation.
kelpie geo set 37.7749 -122.4194 --device "My iPhone"
kelpie geo set 37.7749 -122.4194 --device "My iPhone" --accuracy 10Remove geolocation override.
kelpie geo clear --device "My iPhone"List all shadow DOM hosts on the page.
kelpie shadow-roots --device "My iPhone"Query elements inside a shadow root.
kelpie shadow-query "my-component" ".inner-button" --device "My iPhone"
kelpie shadow-query "my-component" ".inner-button" --device "My iPhone" --pierceShow the soft keyboard by focusing an element.
kelpie keyboard show --device "My iPhone"
kelpie keyboard show --device "My iPhone" --selector "#email"
kelpie keyboard show --device "My iPhone" --type numberDismiss the soft keyboard.
kelpie keyboard hide --device "My iPhone"Check keyboard visibility and viewport impact.
kelpie keyboard state --device "My iPhone"Simulate a reduced viewport (e.g., keyboard present, toolbar visible).
kelpie resize 390 500 --device "My iPhone"Restore full-screen viewport.
kelpie resize reset --device "My iPhone"Check if an element is hidden by the keyboard or outside the visible viewport.
kelpie obscured "#password-input" --device "My iPhone"kelpie wait ".results-loaded" --device "My iPhone"
kelpie wait ".results-loaded" --device "My iPhone" --timeout 15000
kelpie wait ".spinner" --device "My iPhone" --state hiddenWait for a navigation event to complete.
kelpie wait-nav --device "My iPhone"
kelpie wait-nav --device "My iPhone" --timeout 15000kelpie eval "document.title" --device "My iPhone"
kelpie eval "window.innerHeight" --device "My iPhone"Get full device information.
kelpie info --device "My iPhone"
kelpie info # info for all devicesGet viewport dimensions.
kelpie viewport --device "My iPhone"| Command | What it does | Platforms |
|---|---|---|
kelpie toast <message> |
Show a toast overlay on the device | All |
kelpie debug-screens / kelpie debug-overlay get / kelpie debug-overlay set <enabled> |
Inspect or toggle the screen debug overlay | iOS |
kelpie safari-auth [url] |
Start a browser-backed authentication flow | Apple + Android |
kelpie orientation get / kelpie orientation set <mode> / kelpie renderer get / kelpie renderer set <engine> |
Read or change orientation / renderer state | Orientation: iOS, Android, macOS. Renderer: macOS |
All group commands target every discovered device unless filtered.
kelpie group navigate "https://example.com"
kelpie group screenshot --output ./screenshots/
kelpie group fill "#email" "test@example.com"
kelpie group click "#submit"
kelpie group scroll2 "#footer"Find a button on all devices. Returns which devices found it and which didn't.
kelpie group find-button "Submit"Output:
{
"found": [
{"device": "My iPhone", "element": {"tag": "button", "text": "Submit"}},
{"device": "Pixel 8", "element": {"tag": "button", "text": "Submit"}}
],
"notFound": [
{"device": "iPad Air", "reason": "Element not found"}
]
}kelpie group find-element "Sign Up" --role linkkelpie group find-link "Sign Up"kelpie group find-input "Email"kelpie group navigate "https://example.com" --platform ios # only iOS devices
kelpie group navigate "https://example.com" --platform android # only Android
kelpie group navigate "https://example.com" --exclude "iPad Air" # exclude specific device
kelpie group navigate "https://example.com" --include "a1b2c3d4,My iPhone" # only these devices (by ID or name)--include accepts a comma-separated list of device IDs or names. When both --include and --platform are specified, only devices matching both filters are targeted.
Start the CLI as an MCP server (stdio transport).
kelpie mcpConfigure in Claude Desktop / Claude Code:
{
"mcpServers": {
"kelpie": {
"command": "kelpie",
"args": ["mcp"]
}
}
}Start the MCP server with HTTP transport.
kelpie mcp --http --port 8421List approved models, their download status, and Ollama models if available.
kelpie ai listDownload a model from HuggingFace.
kelpie ai pull gemma-4-e2b-q4Delete a downloaded model.
kelpie ai rm gemma-4-e2b-q4Check inference status on a device.
kelpie ai status --device macLoad a model on a device. Supports native model IDs and ollama: prefixed IDs.
kelpie ai load gemma-4-e2b-q4 --device mac
kelpie ai load ollama:llava:7b --device iphoneUnload the current model from a device.
kelpie ai unload --device macRun inference on the device's loaded model.
| Flag | Description |
|---|---|
-c, --context <mode> |
Context mode: page_text, screenshot, dom, accessibility |
--max-tokens <n> |
Maximum tokens to generate (default: 512) |
--temperature <t> |
Sampling temperature (default: 0.7) |
kelpie ai ask "summarise this page" --device mac -c page_text
kelpie ai ask "describe what you see" --device mac -c screenshotEvery command includes structured help designed for LLMs.
Outputs a complete machine-readable reference of all commands, their parameters, expected inputs/outputs, usage guidance, and issue-reporting instructions for unexpected failures or missing capabilities.
kelpie --llm-help # full reference
kelpie click --llm-help # help for specific command
kelpie group --llm-help # help for group commandsLLM help includes:
- Command purpose and when to use it
- Full parameter schema with types and defaults
- Example request/response pairs
- Common error scenarios, failure-reporting guidance, and the repo issue URL
- Related commands and suggested workflows
Natural language explanation of a command for LLM consumption.
kelpie explain scroll2Output:
scroll2 scrolls the page until a target element is visible in the viewport.
Unlike regular scroll, it adapts the scroll distance to the device's screen
size — a phone needs more scroll steps than a tablet to reach the same element.
Use scroll2 when you need to interact with an element that's below the fold.
It will automatically verify the element is visible after scrolling.
Parameters:
selector (required) — CSS selector of the target element
position (optional) — where in viewport: "top", "center" (default), "bottom"
maxScrolls (optional) — safety limit, default 10
Returns: element position, whether it's visible, number of scrolls performed
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Command error (invalid params, element not found) |
| 2 | Network error (device unreachable) |
| 3 | Timeout |
| 4 | No devices found |