Work with results

Every extraction is saved locally under a handle. Re-opening costs no network and no tokens beyond what you read:

from analog import analog, results, history, latest

result = analog("https://example.com")
print(result.handle)          # "20260618-k7m2p9"

again = results.open(result.handle)   # later: rehydrated from disk
newest = latest()
for meta in history():
    print(meta.handle, meta.url)

Artifacts live in your per-user cache dir (~/.cache/analog/results; macOS ~/Library/Caches/analog/results; ANALOG_CACHE_DIR overrides) and store only safe derivatives — structured records and the page’s markdown, never raw HTML. The store is size-bounded (oldest-opened evicted first); analog history shows the disk footprint, and analog rm supports --older-than 30d, --url-contains, and --dry-run.

Inspect and query

analog describe <handle>              # per-field stats: coverage, cardinality, samples
analog distinct <handle> sector       # value counts for one field
analog find <handle> "fintech"        # grep across sections, navigation, and outline
analog diff <handleA> <handleB>       # what changed between two saves
analog rename-fields <handle> text_2=title   # your names, remembered per URL
analog reorder-fields <handle> price name    # named fields first, remembered per URL

The page’s own map

Every result carries the page’s skeleton alongside its records. result.outline reports each significant region with its fate — extracted (pointing at its section), not extracted (with the reason), or page structure — so “not on the page” and “on the page, not extracted” are always distinguishable. result.navigation is the site’s own map: labeled link trees per nav region, collapsed mega-menu content included, all URLs absolute. find searches records, navigation, and outline labels alike, so “where is the pricing page?” is one grep.

Export

analog export <handle> -f csv --fields name,price --where "price < 20" --sort price --limit 10

--where supports =, !=, ~ (contains), and numeric comparisons. Sorting and numeric filters are value-aware: a price field keeps its source display string ("from $5.41") but sorts and compares by the real number. In Python, section.numeric("price") exposes the parallel numbers, and result.to_dataframe() builds a pandas DataFrame with real float64 columns (pip install "analog-sdk[dataframe]").

Exit codes

Uniform across commands so scripts can branch on $? by category: 0 success, 1 command error, 2 usage, 3 auth, 4 backend unreachable, 5 fetch refused/failed (including robots.txt refusals), 6 extraction failed.