tap

package module
v0.4.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 12, 2026 License: MIT Imports: 11 Imported by: 0

README

🚰 Tap

Tap into any website from your terminal.

Install

curl -fsSL https://raw.githubusercontent.com/vaayne/tap/main/scripts/install.sh | sh

Or with Go:

go install github.com/vaayne/tap/cmd/tap@latest

Upgrade later with:

tap upgrade

Browser features use Chrome by default. Check dependencies with tap doctor.

Quick start

Structured data from site scripts
tap site list
tap site hackernews/top
tap site run github/repo repo=vaayne/tap
tap site search weather

Scripts auto-sync from tap.vaayne.com into the local cache. Local overrides at ~/.config/tap/sites/{site}/{script}.js take precedence.

Readable content from any URL
tap fetch https://example.com/article
tap fetch --json https://example.com/article
tap fetch -b https://example.com/app --wait-selector '.content'
Use a visible browser for auth when needed
tap attach chrome
tap browser open https://github.com/login --show
tap site -b github/notifications
tap fetch -b https://github.com/notifications
Reuse your existing Chrome

Chrome must already expose DevTools.

tap attach chrome
tap attach status
tap browser open https://example.com
tap browser snapshot --interactive
tap browser click '#submit'
tap browser click @e1
tap browser text

You can also attach explicitly:

tap attach chrome --browser-url http://127.0.0.1:9222
tap attach chrome --port-file ~/Library/Application\ Support/Google/Chrome/DevToolsActivePort
Browser workflow
tap browser open https://news.ycombinator.com
tap browser open https://github.com --new-tab
tap browser tabs
tap browser switch tab-2
tap browser screenshot --output github.png
tap browser status
Attached Chrome workflow
tap attach chrome
tap attach status --json
tap browser evaluate 'document.title'
tap browser screenshot

If the attached state becomes stale, rerun tap attach chrome.

Command map

tap
├── site        structured extraction from known sites
├── fetch       clean readable content from arbitrary URLs
├── browser     open pages and automate the current browser context
├── attach      connect tap to an existing Chrome browser
├── status      show the active browser context and current tab
├── doctor      dependency and environment checks
└── upgrade     update tap

Common browser-backed flags

These show up on the relevant commands instead of only in global help:

Flag Description
--browser, -b Force browser execution and reuse the resolved browser context
--show Run the browser visibly
--wait Wait a fixed duration after navigation
--wait-selector Wait for a CSS selector
--wait-js Wait for a JS expression
--timeout Set execution timeout
--browser-url One-shot DevTools override
--profile-dir One-shot profile override
--lightpanda, --lp Use Lightpanda instead of Chrome

Compatibility aliases still work:

  • --ws-url -> --browser-url
  • --delay -> --wait
  • --no-headless -> --show

Advanced browser commands

The browser command still includes lower-level tools when needed:

tap browser evaluate ...
tap browser snapshot
tap browser forms
tap browser cookies ...
tap browser network ...

Lightpanda

Backend Platforms Best for
Chrome macOS, Linux, Windows Full browser automation, auth, network interception
Lightpanda macOS, Linux Fast headless rendering without auth-heavy flows

Install or update Lightpanda with:

tap doctor --install

Docs

Agent skill

Tap ships with a built-in agent skill that gives coding agents web access, site scripts, and browser automation.

npx skills add vaayne/tap

Go library

go get github.com/vaayne/tap

client, _ := tap.New()
defer client.Close()

result, _ := client.RunScript(ctx, "hackernews/top", nil)
content, _ := client.Fetch(ctx, "https://example.com", &fetch.Options{Markdown: true})
fmt.Println(content.Markdown)

License

MIT

Documentation

Overview

Package tap provides a unified API for interacting with web pages.

Tap can run site scripts (with QuickJS → Browser fallback) and fetch clean content from URLs via go-defuddle. Both share a common transport layer for HTTP and browser-based network access.

Basic usage: 

client, err := tap.New(ctx, tap.WithSitesDir("./sites"))
if err != nil {
    log.Fatal(err)
}
defer client.Close()

// Run a site script
result, err := client.RunScript(ctx, "v2ex/hot", nil)

// Fetch clean content
content, err := client.Fetch(ctx, "https://example.com", nil)

Index

Constants

View Source 
const (
	EmbeddedTapWebSkillRoot   = "skills/tap-web"
	EmbeddedTapWebSkillConfig = EmbeddedTapWebSkillRoot + "/SKILL.md"
)

Variables

This section is empty.

Functions

func EmbeddedTapWebSkillFS added in v0.4.1 

func EmbeddedTapWebSkillFS() fs.FS

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the main entry point for the tap library.

func New 

func New(ctx context.Context, optFns ...Option) (*Client, error)

New creates a new Client with the given options. The context is used for any startup work (e.g. downloading a browser binary).

func (*Client) Close 

func (c *Client) Close() error

Close releases all resources.

func (*Client) Fetch 

func (c *Client) Fetch(ctx context.Context, url string, opts *fetch.Options) (*fetch.Result, error)

Fetch retrieves a URL and extracts clean content using go-defuddle.

func (*Client) GetScript 

func (c *Client) GetScript(name string) (*script.Script, bool)

GetScript returns a script by name.

func (*Client) ListScripts 

func (c *Client) ListScripts() []*script.Script

ListScripts returns all available scripts sorted by name.

func (*Client) ListScriptsLocalOnly added in v0.3.0 

func (c *Client) ListScriptsLocalOnly() []*script.Script

ListScriptsLocalOnly returns only scripts loaded from the local override directory.

func (*Client) Login added in v0.1.5 

func (c *Client) Login(ctx context.Context, url string, pauseFn transport.PauseFunc) error

Login opens a browser to the given URL and keeps it open until pauseFn returns. Cookies are persisted in the Chrome profile directory so that subsequent script runs are authenticated.

func (*Client) RunScript 

func (c *Client) RunScript(ctx context.Context, name string, args map[string]string) (any, error)

RunScript executes a site script by name with the given arguments. It tries QuickJS first, then falls back to the browser (unless --browser is set).

type Option 

type Option func(*options)

Option configures a Client.

func WithBrowserType added in v0.1.6 

func WithBrowserType(bt transport.BrowserType) Option

WithBrowserType selects the browser backend ("chrome" or "lightpanda").

func WithForceBrowser added in v0.1.1 

func WithForceBrowser(force bool) Option

WithForceBrowser skips QuickJS and runs scripts directly in Chrome.

func WithHeadless added in v0.1.1 

func WithHeadless(headless bool) Option

WithHeadless sets whether Chrome runs in headless mode (default: true).

func WithLocalOverrideDir added in v0.3.0 

func WithLocalOverrideDir(dir string) Option

WithLocalOverrideDir sets a directory that is checked before the main sites cache. Scripts found here shadow cached versions and are flagged as local overrides. Mirrors the path structure: {dir}/{site}/{script}.js

func WithPause added in v0.1.5 

func WithPause(fn transport.PauseFunc) Option

WithPause sets a function that is called after browser navigation, allowing the user to interact (login, solve CAPTCHAs) before script execution.

func WithProfileDir 

func WithProfileDir(dir string) Option

WithProfileDir sets the Chrome user data directory for persistent cookies/storage. Defaults to ~/.cache/tap/chrome-profile-$USER.

func WithSitesDir 

func WithSitesDir(dir string) Option

WithSitesDir sets the directory containing site scripts.

func WithTimeout added in v0.1.1 

func WithTimeout(d time.Duration) Option

WithTimeout sets the execution timeout for scripts and fetches.

func WithWSURL 

func WithWSURL(url string) Option

WithWSURL sets the remote CDP WebSocket URL. If empty, a local Chrome is launched.

type ScriptNotFoundError added in v0.1.1 

type ScriptNotFoundError struct {
	Name      string
	Available []string
}

ScriptNotFoundError is returned when a script name doesn't match any registered script.

func (*ScriptNotFoundError) Error added in v0.1.1 

func (e *ScriptNotFoundError) Error() string

func (*ScriptNotFoundError) Suggestions added in v0.1.1 

func (e *ScriptNotFoundError) Suggestions(max int) []string

Suggestions returns script names similar to the requested name, ranked by relevance.

Source Files

View all Source files

Directories

Path Synopsis
Package browser defines the persistent browser session metadata model used by the planned `tap browser ...` workflow.
 Package browser defines the persistent browser session metadata model used by the planned `tap browser ...` workflow.
cmd
tap command
Package engine provides execution engines for running site scripts.
 Package engine provides execution engines for running site scripts.
Package fetch provides URL content extraction using go-defuddle.
 Package fetch provides URL content extraction using go-defuddle.
Package script handles parsing and discovery of site scripts.
 Package script handles parsing and discovery of site scripts.
Package transport provides a shared network layer for fetching web content.
 Package transport provides a shared network layer for fetching web content.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.