Commands: sessions, tabs and the browser
start, batch, sessions, reset, tabs, status, history, profiles, installers.
| command | args | result |
|---|---|---|
start | (with -s) | {session, socket, log, pid}; detached server, in a context of its own on the shared browser (started if none runs; see Browsers and engines); already_running if it exists |
batch | [<file> | -] [--keep-going] | several steps in one call, one connection: one command per line as on the command line (without navigera -s <name>; # comments; quote arguments with spaces as in a shell) or JSON ops as serve takes them. Every line is parsed before anything runs. Stops at the first failure (--keep-going runs the rest). One response: {steps, ran, results: [{step, do, result}], state, failed} where results holds only what steps read or said beyond the page state (an eval, a text, a select’s selected), state is the page once at the end, notes carry their step (step 3: …) and error names the step and its line. --raw prints each result on its own line (the state when no step read anything). In compact output (the command line’s default) an action says what it changed, as it does alone, except that actions one right after another report once, at the last of them: what they changed together since the last look (a change one made and the next undid is not one). A step that changed nothing says nothing, a title or URL a step changed comes last, and a batch that changed nothing prints ok. Without a session, the steps run on a browser launched for the batch. The shape to use for a multi-step flow: one call, one model turn |
sessions | [--clean [--all] [--idle <s>]] | no session needed: {sessions: [{name, state, pid, age_s, idle_s, browser, url, memory_mib, parent}], shared_browsers: [{socket, pid, memory_mib}], memory_mib}. state is ready, busy (a command is running) or stale (no server answers). Memory: the session server and its own browser (proportional set size on Linux, resident elsewhere); a shared browser counts once, under shared_browsers. --clean quits the sessions idle 300 s or more (--idle <s>), or all of them (--all), removes stale files and closes a shared browser no session uses any more; adds quit, removed and freed_mib |
show / hide | — | the session’s browser on screen, or off it, with the same tabs (the active one stays active) and sign-ins: a --profile browser restarts on its profile, which keeps everything; one navigera launched is replaced by one carrying its cookies and the open tabs’ storage. For a step only a person can do (a login, 2FA, a CAPTCHA). show needs a display. In your own browser (--attach), show brings the session’s tab to the front for you and hands it to you (quit leaves it open), and hide is refused. Not for --electron, an app with windows of its own |
profiles | — | no session needed: {browsers: [{browser, user_data_dir, attach_ready, hand_off, profiles: [{dir, name, email, last_used}]}], navigera_profiles: [{name, dir, running}]}: what --attach and --from can be pointed at |
status | — | {engine, executable, endpoint, attached, browser, version} + state (closed: true once the session’s only tab was closed). browser: shared (N sessions), own or attached. In your own browser (--attach), user_tabs: how many of your other tabs are open. A session server adds server: {pid, started_at, idle_s, parent}. On the shared browser, storage_snapshot_ms: how old the cookies and localStorage a crash would restore are (taken after 1 s without a command; status itself is not one). With --allow-domains, state adds allow_domains: {entries, docs_only, denied: [{host, count}]} |
history | --clear empties it | {history: [{command, at, url, page, locators?}]} (page: the title, the visible h1 and the status/alert messages showing after the action): the actions the session ran (navigation, clicks, typing, selects, uploads, drags, scrolls, tabs, dialogs, and the waits between; not reads or eval), oldest first, the last 1000; one on a ref has the locate of its element from just before it ran (and secret: true for a password field), so bitti from-session can write it as a test |
reset | {tabs, active, url}: a new browser context (no cookies, storage or cache from before) with one blank tab, in the same browser (about 40 ms); the old tabs close; set, routes, credentials, init scripts, the dialog answer, the --allow-domains policy, the downloads --dir and a passkey on authenticator (without its passkeys) stay (reset --all drops them, as in a new session). Chrome only | |
tab-new | [<url>] | {tabs:[{index,target,active,url,title}], active, url}; a tab that was closed under the session (the user closed it, or the page did) shows closed: true until tab-new replaces it, and ops that need it say so |
tab-list | — | same; a tab of yours the session works in has user: true. In your own browser (--attach) also user_tabs: [{target, url, title}], your other tabs, and current: true on the tab you are on, of either list: the one whose window has your keyboard, else the one that came on screen last (you may be typing in a terminal) |
tab-select | <index> (or --index <n>), current (the tab you are on; in your own browser it can be one of yours), or a target id (or its first characters) from tab-list, one of user_tabs too, which stays right when tabs open and close | state |
tab-close | [<index>] (default: active) | state |
dialog | --accept [--prompt-text t] or --dismiss | {dialogs: "accept"|"dismiss"} |
quit (close) | --close-browser, --keep-tabs | {bye: true}; a session server exits with its browser context (a browser of its own: with its browser). --close-browser on a shared browser closes it with this session unless other sessions use it, and says which. Attached (--attach, --profile): browser: "left open", and the tabs navigera opened close (closed_tabs: n) while yours stay (user_tabs_left: n), never the browser’s last tab; --keep-tabs leaves navigera’s open too |
skill | — | prints the agent guide (SKILL.md) |
install-browser | [chrome-headless-shell | chrome] [--channel stable|beta|dev|canary] [--where] | downloads that Chrome from Google’s Chrome for Testing into navigera’s cache, used from then on (see Browsers and engines): {installed, version}; --where prints the directory |
install-skill | [--dir <skills dir>] [--claude | --continue] [--global] | writes <dir>/navigera/SKILL.md with its references/ (default ./.agents/skills, read by Cline and Kilo; --claude: .claude/skills; --continue: .continue/skills; --global: under your home directory) |
Other names the parser takes, for agents used to other tools’ names: navigate
(goto), drag-drop (drag), cookie (cookies), emulate (set),
addinitscript (init-script), close-page (tab-close).
Made from docs/navigera.md.