analog-sdk

Command-line app and Python SDK for Analog. Analog lets any AI understand websites as code. The perception layer for LLMs: webpages in, structured records out. Deterministic, zero-shot, honest. 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 browser downloads automatically on first use. To install it ahead of time:

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.

Extract a page

From the shell:

analog get https://quotes.toscrape.com/js/

Analog renders the page, returns its structured records, saves the result locally, and prints a handle such as 20260719-k7m2p9. Use that handle with analog open, describe, find, distinct, export, or diff without fetching the page again. Run analog --help for the complete command surface.

The same call in Python:

from analog import analog

result = analog("https://quotes.toscrape.com/js/")
print(result.preview())

for section in result.structured_content:
    print(section.label, section.records)

analog() uses the built-in browser by default. Its main controls are reveal_all, load_all, expand_all, and pages; the Fetching guide explains when to use each. Pass fetcher=HttpFetcher() for a plain HTTP request, supply your own Fetcher, or use html= when you already have the page content. For a local markdown conversion with no extraction or account, set mode="local".

Result shape

An AnalogResponse is an orientation view plus the page's data:

• 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.

Read result.preview() first. Then use result.section(label), sections_by_kind(kind), or find(...) to narrow the data before pulling whole record sets. 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

Pages are fetched on your machine by default. The SDK uses a local headless browser, which visits as an unauthenticated user by default. For structured extraction, the SDK sends the URL and rendered page content to Analog. Results return to the SDK and are saved locally unless disabled. Authenticated content is sent only when you explicitly provide it through html= or a custom fetcher. mode="local" is the Markdown-only path that sends nothing.

Raw HTML is used for the extraction request 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.