Superhands CLI

superhands opens and manages Superhands workspaces for host-agent workflows.

Install

cd cli && npm link
# …or once published:
npm install -g @super-hands/cli

Requires Node.js 20+ and system tar.

Usage

superhands login                                  # opens browser → paste token
superhands login --from-browser --json            # start webview-approved CLI auth
superhands login --from-browser --poll shl_...     # poll approval and save token
superhands onboard --agent cursor                 # print onboarding loading/login browser targets
superhands onboard doctor --agent cursor --json    # check onboarding docs, local app, CLI path, and repo context
superhands skill install --agent cursor --json      # install or refresh local agent instructions
superhands skill doctor --agent cursor --json       # check local agent instructions
superhands open https://github.com/owner/repo      # provision a host-agent-ready workspace
superhands open https://github.com/owner/repo/pull/15 --json
superhands ready <workspace-id> --bridge-background --json  # prepare an existing direct workspace
superhands open https://github.com/owner/repo --ref feature-x
superhands repo detect --json                      # detect current GitHub repo and branch
superhands current --json                          # last host-agent-ready workspace
superhands status                                  # fresh status for the current workspace
superhands doctor --repair                         # check and repair local SSH/browser setup
superhands doctor --agent cursor                   # include local agent skill checks
superhands ssh repair                              # reinstall current workspace SSH key/config
superhands bridge start                            # start persistent VM bridge for faster edits
superhands read src/app/page.tsx                   # read a VM file
superhands write src/app/page.tsx --stdin          # write a VM file from stdin
superhands patch --stdin                           # apply a unified diff on the VM
superhands exec -- bun test                        # run a command in the VM workspace
superhands rg "Button" src                         # search the VM workspace
superhands push ./scratch/ src/                    # batch-copy files to the VM with rsync
superhands pull src/app/page.tsx ./page.tsx        # batch-copy files from the VM with rsync
superhands sync --status                           # detect unsynced VM changes
superhands sync                                    # push VM changes to the WIP ref
superhands workspaces list --json                  # list your workspaces (current marked *)
superhands pr create --title "Fix nav" --json      # sync pending edits and open a PR
superhands context --json                          # selected WebView element context
superhands interaction request --prompt "Make this bigger" --wait --apply --json
superhands chat                                   # interactive REPL against an active workspace session
superhands chat --message "Run the tests" --json   # one-shot agent turn, NDJSON events
superhands capabilities                            # machine-readable command catalog
superhands logout

Agent JSON Contract

Every command accepts --json. Successful payloads include ok: true. Failures print a single-line {"ok":false,"error":"...","code":"..."} envelope to stdout and exit with a stable code:

| Exit code | Meaning | |-----------|---------| | 1 | generic failure | | 2 | usage error | | 3 | auth required / rejected | | 4 | workspace, session, or resource not found | | 5 | timeout |

When --json is set (or stdin is not a TTY), the CLI never prompts: commands that would need interactive input fail with a usage error that names the non-interactive alternative (login --token, chat --message, chat --session, write --stdin, ...). superhands capabilities prints the full command catalog, exit-code table, and JSON contract as JSON so wrapping skills can self-configure.

VM-targeting commands (read, write, patch, exec, rg, push, pull, sync, bridge, status, ssh repair, pr create, context, interaction) accept --workspace <id> to address any previously opened or adopted workspace, so parallel agents do not fight over the single "current" workspace pointer. State for each workspace is kept under ~/.superhands/workspaces/.

superhands chat --message "..." --json runs a single agent turn against an active workspace session and streams the raw server events as NDJSON (one JSON object per line: assistant deltas, tool calls, commits), ending with {"type":"result","ok":true,"sessionId":"...","text":"..."}. Use --session <id> to pick a session without a prompt; otherwise the CLI uses the repo detected from git remote get-url origin.

superhands pr create checks the workspace VM for unsynced edits, pushes them to the WIP ref (skip with --no-sync), then opens a pull request against the repo default branch (override with --target <branch>). Title and body are generated server-side when omitted.

superhands login --from-browser --json --origin http://localhost:3000 starts a browser-to-CLI login handoff and returns an approveUrl. Agents should open that URL in the already-authenticated Superhands in-app webview, let the human approve local CLI access, then run the returned pollCommand to save the token to ~/.superhands/config. This avoids external browser launches and token paste.

superhands onboard prints host-agent onboarding URLs and browser policy without opening a browser. Agents should open the returned loadingUrl with the host platform's in-app browser tool first, keep that web view open while CLI setup runs, install or refresh the local Superhands skill with superhands skill install --agent <agent>, and navigate it to loginStateUrl only after the local skill and host browser tools are ready.

Direct workspace handoffs from the /d/<workspaceId> toolbar are different from generic onboarding: the deeplink prompt is self-contained and must not depend on a preinstalled Cursor skill. It should run superhands ready <workspaceId> --origin <url> --browser-url <url> --bridge-background --json through npx -y @super-hands/cli@latest. If the CLI lacks auth, ready --json returns nextAction: "browser_login_then_retry" with login.approveUrl, login.pollCommand, and retryCommand; agents should follow those fields exactly and must not install or update a skill as part of the direct handoff. Bare Modal URLs such as ...?sh_surface=direct are not transferable across Cursor webview cookie jars unless they include sh_token and sh_origin; when those params are missing, ready returns the /d/<workspaceId> URL so the app can mint a fresh direct token before redirecting back to Modal. Direct handoffs use --bridge-background: opening the toolbar/page is not blocked on bridge startup, but the bridge is warmed immediately because a follow-up edit/search/test task is likely. For compatibility with already-open Cursor chats that contain an older direct prompt, ready upgrades --no-bridge to background bridge warmup when the browser URL is a direct Modal URL or /d/<workspaceId>.

superhands skill install and superhands skill update fetch the latest host-specific instructions from /agents/skills/* and write them to the user's local agent surface:

• Codex: ~/.codex/skills/superhands/SKILL.md
• Cursor: ~/.cursor/skills/superhands/SKILL.md
• Claude Code: ~/.claude/commands/superhands.md
• Generic: ~/.superhands/agents/superhands.md

The CLI writes only a superhands-managed block, so user-authored content in an existing file is preserved. superhands skill doctor --json compares that managed block against the current /agents/skills/* template version, origin, source URL, and CLI invocation, so stale local skill installs fail clearly.

superhands onboard doctor --json is the machine-readable preflight for agent-native onboarding. It checks the loading URL, public markdown docs, development context endpoint, CLI path/package resolution, and whether the current directory is a GitHub repo. Use it before asking the user to authenticate. superhands repo detect --json is the smaller repo-only check for agents that need to decide whether the current host workspace is already opened in the target repo.

superhands open creates a /w workspace from a GitHub repo or PR URL. Plain repo URLs start a new sh/<id> branch; PR URLs open or reuse the PR source branch. Use --ref <branch> to open or reuse a specific branch, and --fresh to force a new workspace when reuse is available. By default it opens a short-lived pre-authenticated browser URL so fresh in-app browser profiles land directly in the workspace, waits for the Modal SSH tunnel, installs a local ~/.superhands agent key into the VM (agent_ed25519 by default; platform adapters use platform-specific keys such as codex_ed25519 and cursor_ed25519), writes a managed Host superhands-<id> entry to ~/.ssh/config, and prints the remote workspace path for the host platform's remote connection flow. Use superhands ready <workspaceId> for a workspace opened from /d; it adopts the workspace, requests SSH-enabled reprovisioning for old no-SSH direct workspaces, writes local SSH state, warms the bridge by default, and returns deterministic VM command templates. Direct-toolbar deeplinks pass --browser-url <url> with the exact direct Modal URL that was open when "Edit in Cursor" was pressed; agents should open the returned browserOpenUrl in the host in-app browser after ready succeeds, confirm the direct toolbar/page loaded, and then stop unless the user asks for a follow-up edit task. The JSON payload includes nextAction: "open_browser_and_stop" and stopAfterBrowserOpen: true for that terminal handoff. Direct-toolbar deeplinks use --bridge-background so bridge startup does not block preview open but is likely ready before the first edit. If an older direct handoff still invokes ready --no-bridge, the CLI treats that as stale and warms the bridge in the background for direct Modal and /d/<workspaceId> browser URLs. superhands adopt <workspaceId> is the lower-level adoption command and accepts --bridge to warm the same bridge. Use superhands ssh repair to reinstall the current workspace key and refresh the managed SSH config block. Use --no-browser whenever another tool, such as an in-app browser, will open the returned workspace URL; otherwise open launches the system browser.

superhands status fetches the latest current workspace state from Superhands. superhands doctor verifies the saved token with the server, checks CLI/server version compatibility, validates the current workspace pointer and SSH config, and can refresh the local SSH setup with --repair. Commands that contact the Superhands API for an adopted workspace, including whoami, status, ssh repair, sync, context, and interaction, accept --origin <url> so agent deeplinks can pin the intended environment even when local CLI config is stale.

For agent-driven VM edits, prefer the Superhands file commands over raw one-off SSH commands. superhands bridge start uploads a small Node helper to the VM, binds it to 127.0.0.1, and forwards it to a local port through SSH. Then read, write, patch, exec, and rg reuse that bridge for fewer SSH round trips, automatically falling back to SSH if the bridge is unavailable. Managed ~/.ssh/config entries also enable OpenSSH multiplexing (ControlMaster auto, ControlPersist 10m) so fallback SSH commands avoid repeated handshakes. Use --ssh on an individual file command to bypass the bridge. Use push and pull for batched rsync transfers when an agent needs to stage or retrieve multiple files at once; --delete is opt-in.

superhands sync --status asks Superhands to inspect the current workspace VM for uncommitted git changes. superhands sync commits those VM changes, pushes them to the workspace-scoped WIP ref, and makes the Superhands workspace Create PR flow eligible without going through the internal Superhands agent.

Host-agent /w pages write the selected inspector element to superhands context --json. For visual prompts that need a user-chosen value, superhands interaction request --wait --apply --json creates a pending WebView interaction, waits while the user tunes and confirms the property panel, then hands the confirmed structured edit payload to the Superhands source-edit fast path before returning JSON. If the fast path is unsupported, the JSON still includes the payload so an agent can make a focused fallback source edit.

superhands chat auto-detects the repo from git remote get-url origin and attaches to your most recent active workspace session for that repo (creating the workspace itself still happens in the browser). Type messages, press enter to send. Ctrl-D or /exit leaves the REPL.

Config lives at ~/.superhands/config (mode 0600). Override the saved target origin with SUPERHANDS_ORIGIN=http://localhost:3000; command-level --origin takes precedence when available.

Developing With Local App And CLI

To test a local CLI build with the local app server, pass the CLI entrypoint and origin in the first-run prompt, or run the same commands directly:

node "$PWD/cli/bin/superhands.js" onboard --agent cursor --origin http://localhost:3000 --json
node "$PWD/cli/bin/superhands.js" skill install --agent cursor --origin http://localhost:3000 --json
node "$PWD/cli/bin/superhands.js" skill doctor --agent cursor --origin http://localhost:3000 --json

In local app development the agent can discover the CLI path from:

curl -sS http://localhost:3000/api/agent/dev-context

That endpoint also returns API/CLI compatibility versions, public skill template versions, local plugin wrapper paths, and a best-effort git SHA for the running checkout.

Releasing

See PUBLISHING.md for how to cut a new npm release.