Docs

webnav is a CLI an AI agent shells out to. It navigates sites deterministically and hands back compact evidence; the agent does all the judgment. Full reference lives in the README.

Install

git clone https://github.com/lucyfuur94/webnav-core
cd webnav
npm install        # Node 18+
npm link           # puts `webnav` on PATH (runs source via tsx — no build)
webnav --help      # the tool menu

Needs playwright-cli on PATH.

How the map grows

A fresh install seeds one worked example — saucedemo.com — into a shared, per-user map at ~/.webnav/webnav.db. It persists and self-heals on use: when a remembered step drifts, the walk asks once, then writes the fix back so the next run is deterministic again. Mapping a brand-new site is a recording flow (roadmap: one-command mapping + shareable map packs).

Self-host route (free)

webnav walk --start www.saucedemo.com:login \
            --goal  www.saucedemo.com:checkout-complete
# pauses at forks for the agent; resume with:
webnav walk-resume <session> --ref <e42>
webnav walk-resume <session> --classify safe   # at a commit point

Hosted route (shared knowledge) — coming soon

The hosted layer — one maintained, self-healing central map served over an API — is coming soon. When it ships: get a free key, save it, then add --hosted. The map is fetched over the network; your credentials still load locally. Watch the repo for the launch.

webnav login wn_live_xxx          # free key — available at launch
webnav walk --hosted \
  --start www.saucedemo.com:login \
  --goal  www.saucedemo.com:checkout-complete

Credentials

Store site logins locally — never in the map, never sent to the hosted service:

webnav creds set www.saucedemo.com username=standard_user password=secret_sauce
# stored at ~/.webnav/credentials.json (chmod 600); the walk auto-fills them

Core verbs

• recall — replay a goal’s route → evidence bundle (the agent ranks)
• search — multi-provider open-web search → extracted evidence
• walk / walk-resume — deterministic multi-step travel with pause/resume
• locate / route / hop — place lookup + the internet graph
• dev outline / dev dashboard — inspect what’s mapped

Run webnav --help for the full menu.