Repository navigation
Surf now tells you when something didn't work. Clicks, typing, dropdown choices and locate actions used to print OK even when nothing happened. Now they fail with the reason, for example a disabled button, a cookie banner in the way, or text longer than the field allows. Keeping Surf current takes one command, surf update, and setup no longer needs an extension ID copied from Chrome. surf read also shows more of real pages, including forms built from custom components, styled checkboxes, and what each field currently holds.
Highlights
- Clicks and typing fail honestly. Surf says why an action didn't work (
e5 is disabled,e2 is covered by dialog "Cookie consent") instead of printingOK. Clicks wait for the element to be ready and use a real mouse click, andlocateno longer clicks "Save draft" when you asked for "Save". - One command to update.
surf updateupdates the CLI, the browser connection and the agent skill, then reloads the extension. When the parts get out of step, every command warns you. readsees more of the page. It now lists form fields inside custom components (such as SmartRecruiters job forms) and styled checkboxes, along with what each text field holds. Passwords are never shown. It also counts the controls further down the page.- New commands.
surf checkandsurf uncheckset a checkbox to the state you want.surf page.text --refprints a field's whole value.surf type --escapestypes real newlines and tabs.
Need to know
| Who | What to do |
|---|---|
| Existing Surf users | Surf's extension ID changes once. Run surf install, then reload Surf in chrome://extensions. Settings saved in the old copy, such as Debug Mode, don't carry over. |
Scripts that relied on OK |
Actions that used to print OK without working now exit with an error. These include clicking a disabled or covered element, an ambiguous locate --action, text too long for its field, and a dropdown value with no matching option. |
Highlights
- When a click, typed text, dropdown choice or
locateaction doesn't work, Surf now fails and says why (e5 is disabled,e2 is covered by dialog "Cookie consent") instead of printingOK. Clicks also wait for the element to be ready and use a real mouse click. surf updateupdates the CLI, the browser connection and the agent skill, then reloads the extension, all in one command.surf installno longer asks for an extension ID.surf readsees more of the page: form fields inside custom components, styled checkboxes, what each text field holds (never passwords), and a count of controls further down the page.- New
surf checkandsurf uncheckset a checkbox to the state you want, andsurf page.text --refprints a field's whole value. - If you already use Surf, its extension ID changes once: rerun
surf install, then reload Surf inchrome://extensions.
Added
surf checkandsurf uncheckset a checkbox to the state you want - Clicking a checkbox toggles it, so an agent had to read its state first or risk unticking a box that was already ticked by default.surf check <ref>andsurf uncheck <ref>leave a checkbox, switch or radio alone when it is already in that state (e6 was already checked; nothing clicked.), and otherwise click it like a real mouse would, so pages that keep their own state in click handlers (such as React apps) see the change. If the control still isn't in the requested state after the click, the command fails.uncheckon a radio button fails and says to pick another option in its group. Thanks to @morgan55555 for #436.- Surf can start your browser for you - Set
"browser": { "autostart": true }insurf.jsonand a command run while the browser (or its Surf host) isn't running starts it, waits up to 30 seconds for Surf to connect, then runs.surf go <url>opens the browser on that page instead of a blank new tab. Pick the browser with"app"(chrome,chromium,brave,edge,arcorhelium) or give the exact command with"command";"timeoutMs"changes the wait. Thanks to @morgan55555 for #424. surf doctorshows the CLI, native host and extension versions - The CLI, native host and loaded extension come from one package but pick up a new version at different times, so they can run different versions.surf doctornow reports all three versions and fails with aversion-skewcheck, naming the fix (surf update), when they differ.- Every command warns when the CLI, native host and extension versions differ - The native host now sends its own version and the extension's with each response, and when either differs from the CLI's, the command prints one line on stderr, such as
surf: version mismatch (cli 2.26.0, host 2.25.0, extension 2.25.0). Run `surf update`.The command's output and exit code stay the same, and a host too old to send its version prints no line. surf updateupdates surf and reloads the extension in one step - Updating used to mean reinstalling with npm, rerunningsurf install, and clicking Reload in chrome://extensions, and a missed step left the CLI, native host and extension on different versions.surf updatereinstalls with the npm that installed this surf (not whichever npm is first on PATH), or runsnpm ci && npm run buildin a linked repo checkout, refreshes the native host for the browsers that already have it and the agent skill links, asks the extension to reload itself, and prints the versions before and after (--jsonfor{before, after, steps}). It changes nothing for an install it doesn't recognize. The first time, the running extension is too old to reload itself, sosurf updateasks you to reload it once in chrome://extensions.surf installlinks the agent skill to the installed package - The Surf skill for Claude Code and pi was copied by hand, so it fell behind the CLI.surf installnow links~/.claude/skills/surfand~/.pi/agent/skills/surfto theskills/surffolder of the surf-cli you ran it with, so the skill updates with surf. It only links where that agent's skills folder already exists, repoints an existing link, and never touches a skill folder you made yourself: it says it kept it and that you can remove it and rerunsurf installto switch. It skips pi when pi already loads surf-cli as a package, so the skill isn't loaded twice.surf installno longer needs an extension ID - Chrome gave each unpacked Surf an ID based on the folder it was loaded from, so you had to copy it fromchrome://extensionsintosurf install <extension-id>. The extension now carries a fixed public key, so every Surf build has the IDoaclimdkkglbnpekeignmjenkodkaaka.surf install <extension-id>still works for a fork or a build with a different ID. If you already use Surf, its extension ID changes once: rerunsurf install, then reload Surf inchrome://extensions. Until you reload, the old copy keeps working; afterwards a disabled copy under the old ID stays listed until the browser restarts. Settings the old extension stored, such as Debug Mode, don't carry over to the new ID.surf page.text --refprints one field's whole value or one element's text - To check a long note or cover letter before sending it, you had onlysurf read, which cuts a field's value at 80 characters and joins its lines, or asurf jscall with a CSS selector.surf page.text --ref <ref>now prints a text field's, textarea's or editable area's whole current value, newlines included, and any other element's rendered text. A secret field (the same onesreadshows as[value hidden]) fails withe4 is a secret field, so its value is not shownand its value is never sent. Thanks to @morgan55555 for #449.surf type --escapestypes newlines and tabs - Putting a real newline or tab into a shell argument is awkward, and smaller models often can't, sosurf type "line1\nline2"typed a backslash and ann. With--escapes,\n,\t,\rand\\in the text become a newline, tab, carriage return and one backslash before typing, on everytypepath (--ref,--intoand at the cursor). Any other backslash sequence is typed as written. Without the flag,surf typetypes the text literally as before. Thanks to @morgan55555 for #451.
Fixed
surf readsays how many controls it left out for being off-screen -surf readlists only the controls on screen unless you pass--all, and gave no sign that more were further down the page, so agents read a page, missed the controls below the fold, and sometimes decided the page was broken. When controls are left out for being off-screen,surf readnow ends with a line such as+142 elements off-screen: surf read --all. There's no such line when nothing was left out, or with--allor--ref. Thanks to @morgan55555 for #452.locateno longer acts on the wrong element -surf locate.role,locate.textandlocate.labelwith--actionused to act on the first element whose name contained your words, and printedOK, sosurf locate.role button --name "Save" --action clickcould click "Save draft", and--name "Delete"on a list clicked the first row's Delete button. Now an element whose name is exactly what you asked for wins over partial matches, and when more than one element still matches, nothing is clicked or filled: the command fails and lists each match with its ref, so you can act on the one you mean withsurf click <ref>.- Typing into a field that can't take the text fails instead of saying OK -
surf type "<text>" --ref <ref>,surf type "<text>" --into <selector>andsurf form.fillused to write past a field's character limit, overwrite a read-only field, and printOKwhen the page threw the text away. Now a read-only or disabled field, or text longer than the field allows, fails with the reason, such ase1 accepts at most 4 characters, but 8 were given, and nothing is written. If the field still holds its old value after typing, or the page empties it, the command fails withdid not keep the typed text. A field that reformats what you typed, such as a phone number mask, still counts as success. Aform.fillthat fills some fields but not others now fails too, says how many it filled, and names each field it couldn't fill. - Errors say what went wrong instead of "Try refreshing the page" - When a page command such as
read,click,type,locate.*orwait.elementfailed for any reason, Surf saidContent script not loaded. Try refreshing the page., even when Surf was working on the page and something else went wrong. Refreshing then threw away what was typed into the page. Surf now says this only when its script really isn't answering on the page. A command cut short because the page navigated or closed says so, and any other failure shows its real error. - Clicking by ref only clicks what a user could click -
surf click <ref>andsurf locate.* --action clickused to fire the element directly and printOKfor a disabled button, click straight through a cookie banner or dialog covering it, and do nothing on buttons that ignore script-made clicks. Now Surf waits up to 5 seconds for the element to be visible, enabled and not covered, scrolling it into view if it is hidden inside a scroll box, then clicks it with a real mouse event. If it never becomes clickable, the command fails with the reason, such ase5 is disabledore2 is covered by dialog "Cookie consent", and nothing is clicked. - A ref from an earlier page no longer clicks something on the current one - Every page used to number its elements from
e1, so after a navigation or reload an old ref such ase2named a different element on the new page, andsurf click e2acted on it and printedOK. Within a tab, a new page now numbers its elements after the ones earlier pages used, so refs never repeat. Using a ref from an earlier page fails and names that page, such ase2 is from an earlier page in this tab (https://example.com/plan). Run surf read to get current refs.A page you go back to from the browser's back/forward cache keeps its own refs. - Custom buttons, links, tabs and menu items show their names - A control built from a
<div>or<span>with a role such asbutton,link,tab,menuitemoroptiongot an empty name when its text sat inside a child element or was shorter than 3 characters, sosurf readlisted<div role="button"><span>Save</span></div>asbutton "", andsurf locate.role button --name "Save" --action clickrefused because it couldn't tell such buttons apart. These controls now take their name from their text, as<button>already did, sosurf readshowsbutton "Save"andlocatepicks the exact one. Table cells and headers are named from their text too. See #430. - A click that can't be a real mouse click says so - When
surf click <ref>orlocate.* --action clickcouldn't send a real mouse click, it fell back to clicking the element inside the page and still printed onlyOK, so you couldn't tell why a site ignored it. Now the output adds a line such asClicked e3 inside the page, not with the mouse, because its tab is hidden (a background tab, or a window behind other windows). If nothing happened, switch to the tab (surf tab.switch <id>) or bring its window to the front and retry.Clicks in hidden tabs, inside frames, or when Surf can't attach its debugger still go in the page after the same checks, and now say why. After you click Cancel on Chrome's "is debugging this browser" bar, the next ref click attaches again and sends a real mouse click instead of quietly falling back. - Form fields inside custom components are now visible - Pages that build their forms from custom elements with open shadow roots, such as job application forms on SmartRecruiters, showed none of their fields in
surf read, andsurf locate.label "First name"found nothing. Surf now reads through open shadow roots, so those fields and buttons appear with their names (taken from the label inside the component), you can click and type into them by ref as usual, andlocate.label,locate.roleandlocate.textfind them too, acting on the field inside the component rather than on the component that shares its id. Closed shadow roots stay unreachable. Thanks to @morgan55555 for #437. - Selecting an option that doesn't exist fails instead of saying OK -
surf select <ref> <value>printed a warning but exited 0 when no option matched, andsurf form.fillquietly emptied a dropdown it couldn't match. Both now fail and change nothing, for examplee5 has no option matching "nowhere" (by value), so nothing was selected.form.fillmatches a dropdown option by its value or its visible text. readshows what a field holds, and never a password -surf readlisted a text field by its label or placeholder but not its contents, so checking whatsurf typeor the user entered took asurf jscall. Text inputs, textareas and editable areas now show their current value, such astextbox "hello@example.com" [e85] type="email" placeholder="hello@example.com" value="hello22", cut at 80 characters with.... Secret fields show[value hidden]instead:type="password"fields, fields whoseautocompleteiscurrent-password,new-password,one-time-codeor acc-card token, and fields the page masks on screen with-webkit-text-security. The page-change report aftersurf typenow hides masked fields' values too.readalso no longer prints a password as the field's name: a password field Surf couldn't otherwise name, such as one inside a<label>withoutfor, used to appear astextbox "<the password>". Thanks to @morgan55555 for #434.- On Android,
surf doctorsays why it can't work and what to do instead - In Termux,surf doctorand a failed command told you to make sure the browser was running with the Surf extension, but no Android browser can run the extension's native host. Nowsurf doctorfails with that reason and both point to running the browser on a desktop machine and connecting withsurf --remote <host>:<port> --remote-credential <file>. Thanks to @shankarkrupa for #417. surf installsets up the host from the surf you ran it with - With two surf-cli installs on PATH (for example one from a Node version manager and one from Homebrew),surf installpointed the browser's native host at whichever copynpm root -gnamed, so the browser could run a different, older host than yoursurfcommand. It now always uses the host from the same install as thesurfyou ran.SURF_HOST_PATHstill overrides it.- Page text no longer fills up with CSS rules -
surf page.textand the--- Page Text ---part ofsurf readtook every bit of text in the page's markup, so on sites that put their styles and scripts inside the page body (such as Tilda sites) the output was mostly CSS and JavaScript. They now return the text the page actually shows. Styles, scripts and hidden content such as collapsed sections ordisplay:noneblocks are left out. Thanks to @morgan55555 for #435. page.htmlandpage.savework without--selector-surf page.htmlandsurf page.save --output <file>failed withValue is unserializableunless you passed--selector, because Chrome refuses an empty argument in the script it runs. They now return the whole document with its<!doctype>line. Thanks to @doctorguile for #423.surf readlists form fields the page draws over with a transparent input - Styled checkboxes, radios and other fields often leave the real<input>atopacity: 0and draw their own box beneath it, sosurf readleft the field out unless you passed--include-hidden, andsurf checkorsurf clickon it reportedno visible change. Now aninput,selectortextareathat is transparent but otherwise shown appears insurf readand its YAML output,surf checkreports its change (e3 checkbox "I agree" now checked), and an old ref to it still finds it after the page re-renders. Other transparent elements, such as faded-out menus and buttons, stay hidden. Thanks to @morgan55555 for #450.