analog-sdk

Command-line app and Python SDK for Analog. Analog lets any AI understand websites as code. Analog is a web interface built for AIs. It converts webpages into the things they contain — products, articles, events, and other records — so AIs can query, compare, export, and use them directly. The extraction pipeline contains no LLMs. Given the same page URL and HTML, the same engine produces the same records. A live page's HTML can change between fetches.

Install

macOS, Linux, or WSL:

curl -LsSf https://getanalog.io/install | sh

Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://getanalog.io/install.ps1 | iex"

The installer puts the analog command on your PATH as an isolated uv tool. If uv is already installed:

uv tool install analog-sdk

Homebrew users can instead run brew install getanalog/tap/analog; pipx install analog-sdk and pip install analog-sdk in a managed virtual environment also work with Python 3.10+.

Analog's built-in browser downloads automatically on first browse use. Supplying a page file to view needs no browser download. To prepare the fallback:

analog browser install

The complete installation options and CI guidance live in the installation guide.

Create an account and connect this terminal (an invite code is required during the private alpha):

analog signup

For an existing account or another machine:

analog login

On an interactive machine without a browser:

analog login --no-browser

Open its link in a browser elsewhere, then paste the one-time handoff at the hidden prompt.

The credential is stored locally and picked up automatically by the SDK, CLI, and MCP server; see authentication for its storage, scope, and revocation model.

View a page from your browser

Use your agent's browser to open Analog's About page. The browser handles navigation and interaction; Analog makes the captured content available for searching, inspection, and reuse.

For a harness browser with supported JavaScript evaluation and Node filesystem access, prepare a reusable helper at a new path:

analog browser capture-script --output ./analog_capture.mjs

Import the returned path inside the browser tool's runtime, then call capturePage({evaluate, path}) with its supported evaluator and a new absolute capture path. Return only the receipt. The Codex GUI capture recipe shows the binding and capture limits; other environments need their own supported evaluator. Capture does not change the live page.

Use the capture's actual path and an unused saved name:

analog view ./about.capture.json --save-as about --find "Frankie"
analog view about --find "Marcus" --find "Frankie"

The first command validates the capture, sends its prepared HTML and actual URL for extraction, saves the result, and returns matching evidence. Matches go to stdout; the handle and capture qualifications go to stderr. The second command searches the saved result locally, without fetching or extracting again. Observed shadow/frame omissions remain qualified in the saved result.

Already have ordinary HTML? Use analog view ./about.html --url https://getanalog.io/about/ --save-as about --find Frankie. The URL identifies the captured page; view never fetches it. --mode local converts a supplied page to Markdown without sending its HTML or URL to Analog.

Request an overview with analog view about, or ingest a file with --save-only when you just want its receipt. Use handles or names with describe, distinct, export, and diff as the task requires. For batch JSON, queries contains each pattern and indexes into the shared matches array; an empty index list means no matches in this capture.

When you need Analog's browser

If your environment cannot supply a capture, or you choose Analog to acquire the URL, use its built-in browser:

analog browse https://getanalog.io/about/ --find "Frankie"

browse renders, saves, and searches in one command. It starts a fresh browser session, separate from your browser's sign-in. The printed handle identifies this result for later use; analog view latest --find Marcus searches the most recent save. Bare browse URL returns a receipt. --json and --markdown select full data; --no-save requires one of those formats. --find --json returns full matching objects; --find cannot combine with --markdown or --no-save. Put --guidance before browse or view for an optional next action.

In Python

Supply HTML captured in your environment:

from pathlib import Path
from analog import analog

html = Path("about.html").read_text(encoding="utf-8")
result = analog("https://getanalog.io/about/", html=html)
print(result.find("Frankie"))

Omit html= to use Analog's built-in browser. analog() also accepts an HttpFetcher or a custom Fetcher; reveal_all, load_all, expand_all, and pages control built-in acquisition. The Fetching guide owns those options. mode="local" converts to Markdown without hosted extraction. Use result.preview() when an overview would help; guidance=True adds an available next action, and complete=True includes hidden fields in its summary.

Result shape

An AnalogResponse holds the page's data and offers views over it:

• sections is the readable document sequence: extracted record sections and locally rendered MarkdownSection regions together in page order. Its order comes from the response's required document_section_plan; an unresolved prose region remains present with empty markdown instead of disappearing.
• structured_content is the ordered list of extracted Section objects.
• Each section carries records, field metadata, and its own markdown.
• collections provides high-confidence unions over compatible physical sections, with one identity-deduplicated local records view and pointers back to every placement.
• outline reports the significant page areas and what happened to them.
• navigation preserves the page's labeled link trees.
• warnings, pagination details, and browse actions disclose partial or uncertain coverage.
• handle identifies the local saved result.

Use find(...) for a known value, result.section(label) or sections_by_kind(kind) for a known area, or result.preview() when an overview would help. Export helpers include to_json(), to_yaml(), to_csv(), and the optional pandas-backed to_dataframe().

A page can contain several unrelated sections: for example, a catalog, a reviews area, and a comparison table. Analog preserves those boundaries instead of silently pooling unlike records. When several physical sections are confidently parts of the same dataset, result.collections[0].records offers the combined view while collection.sections preserves every authored placement. Work with one section, one Collection, all sections of a shared kind, or project common fields explicitly. Field names are a best-effort starting point when the page supplies no useful label; field values preserve what the page rendered. Coverage notes call out withheld content, unusual rows, page-owned truncation, pagination, and interactive controls that were available but not used.

Results are saved by default as structured records, ordered Markdown regions, and page markdown, never raw HTML. Reopen them with analog.open(handle), latest(), and history(); pass save=False to skip persistence. The Results guide covers querying, field statistics, filters, numeric values, exports, renaming, several sections on one page, retention, and CLI exit codes. Exact Python names, parameters, and return types are in the compact Python API reference.

Data flow and privacy

For URL acquisition, pages are rendered in a browser on your machine by default. The built-in browser starts a fresh session and does not use your browser profile, cookies, or saved credentials. For structured extraction, the rendered page content and its URL are sent to Analog. Results return to the SDK and are saved locally unless disabled. Signed-in page content is sent only when you explicitly supply it. mode="local" converts the page to Markdown on your machine and sends nothing to Analog.

Supply signed-in content through a capture or HTML file to view, Python's html=, or a custom fetcher. Your capture files remain on disk; view does not delete them. Raw HTML is used for extraction and local Markdown conversion, then dropped rather than written to the result store. Point Analog at content that is acceptable to send. Local and private-network targets are declined by default. The built-in browser checks redirects, client navigation, subresources, and WebSockets before connecting, including whether each hostname currently resolves only to public addresses. Reaching a trusted development server or intranet host requires the explicit allow_private=True opt-in. This request guard does not pin Chromium to the DNS answer Python checked; the linked security guide states that rebinding limit.

Library failures derive from AnalogError, with narrower types for authentication, connectivity, rate limits, version skew, fetch refusals, robots.txt decisions, incompatible sections, and saved-result problems. Catch the narrow type when your application has a specific recovery path; otherwise catch AnalogError at the integration boundary. The API reference lists the complete exception inventory.

Extraction URLs are never logged. A quality report includes the URL you explicitly submit; it never includes page content. Read Privacy for the complete data contract, Security for credential and network boundaries, and Fetching for fetching identity and controls.

Where to go next

• Quickstart — the shortest path from installation to a useful saved result.
• Fit check — decide whether a page belongs in a structured extraction workflow before spending one.
• Fetching and Results — control page capture, then query and export what came back.
• MCP server — expose the same workflow as tools to an MCP client.
• Limitations and Troubleshooting — known boundaries and fixes for common failures.

The docs site is the durable owner for task guidance; this README stays a short landing page. analog docs prints its URL when you need to hand the documentation to another process, and the core docs are also included in the site's /llms.txt and /llms-full.txt views.

Use analog feedback to report a poor extraction or request a feature. Use analog contact or email hello@getanalog.io for support.

License

MIT — see LICENSE.