Write agent scripts

beaconctl nodejs accepts a complete script on standard input. The bundled Node.js runtime has browser helpers already loaded, and each invocation starts with fresh JavaScript variables. Browser tabs and site storage remain in the app between script invocations.

Discover the installed helpers

Print all helper signatures, or inspect one contract:

beaconctl nodejs <<'JS'
cliLog(help());
cliLog(help('click'));
JS

Use top-level await for asynchronous work. Node globals, require(), and dynamic import() are available; static imports are not supported in these stdin scripts.

Observe before acting

Declare a task, navigate its working tab, and read a snapshot before choosing an element:

beaconctl nodejs <<'JS'
await useOrCreateTaskSpace('inspect-example');
await openOrReuseTab('https://example.com', { wait: true });
cliLog(await snapshotText());
cliLog(await js('document.title'));
JS

snapshotText() returns full-page semantic text. snapshot() returns structured data and defaults to the viewport. Snapshots expose element references such as @12 and semantic selectors. Use only references in the latest exported snapshot, and observe again after navigation or a page change.

click, fillInput, and other actions accept current references or selectors. Native coordinates use viewport CSS pixels. Selector actions dispatch synthetic events; native input works in the selected tab of an open, non-minimized browser window.

Keep state in the right place

Reuse the task name to resume its tab during the current browser session. Node variables do not survive between invocations. Code passed to js or elementEval runs in the page and cannot capture variables from the surrounding Node script.

Global helper timeouts use seconds; SDK Page methods and low-level JSON commands use milliseconds. Wait for an expected URL, selector, or page state after an action.

End or hand over a task

completeTaskSpace() finishes the task and retains its tabs for review. closeTaskSpace() closes managed tabs. Both preserve unrelated human tabs. Scripts do not finish tasks automatically when they exit or fail.

If a command reports control.user_owned, stop browser actions. The person must explicitly return control before the agent continues. WebKit has no Chromium CDP endpoint; browser.info lists the engine's current limitations.