@heysnap-ai/web

An agent-friendly CLI for working with the web — exposes search, scrape, and an agentic research command that produces a structured, cited markdown report. All traffic routes through the local ank1015 cloud-server gateway, so no third-party provider keys live on the machine.

npm install -g @heysnap-ai/web
web --help

Quick start

# Required env, on the machine container:
export CLOUD_SERVER_PUBLIC_URL=http://host.docker.internal:4100
export ANK1015_MACHINE_TOKEN_FILE=/opt/ank1015/machine-token

# Search the web
web search "claude opus 4.7" -n 10

# Scrape a single page
web scrape https://firecrawl.dev -q > page.md

# Agentic research → saves a markdown report under /tmp/web-research/
web research "state of small LLMs in 2026"

Commands

| Command | What it does | |---|---| | web search | Web search via the gateway's Firecrawl route. Titles, URLs, snippets. Operators like site:, "...", -term, filetype: pass through. | | web scrape | Fetch a single URL as markdown / HTML / links / screenshot. Large pages auto-saved to a temp file with only a preview printed inline. | | web research | Agentic loop: searches, scrapes, and synthesizes a structured markdown report. Per-scrape compression by a small extractor model lets it span ~10–15 sources. |

Run any command with --help for the full reference, or see docs/:

• docs/cli.md — top-level overview and conventions
• docs/search.md
• docs/scrape.md
• docs/research.md

Conventions

• Data goes to stdout, diagnostics to stderr — pipes stay clean.
• Output auto-switches: TTY → pretty, pipe → JSON. Override with --json / --pretty / -q.
• Exit codes: 0 ok · 1 usage/validation · 2 API/network · 3 research-specific "no report produced".

Auth

Two env vars, no provider keys:

CLOUD_SERVER_PUBLIC_URL=http://host.docker.internal:4100
ANK1015_MACHINE_TOKEN_FILE=/opt/ank1015/machine-token

ANK1015_MACHINE_TOKEN_FILE is a path to a file containing the bearer token (per the Docker-secret _FILE convention). The CLI reads and trims it at startup. The gateway routes Firecrawl traffic to ${CLOUD_SERVER_PUBLIC_URL}/firecrawl and OpenAI Responses-API traffic to ${CLOUD_SERVER_PUBLIC_URL}/llm/openai/v1.

Development

npm install
npm run dev        # tsx watch
npm run typecheck
npm test           # unit tests (no network)
npm run build      # → dist/

Integration tests spawn the built CLI as a subprocess. Set the gateway env above to run live tests:

npm run test:integration

License

UNLICENSED.