Reference

Precise interfaces, in the order you are likely to need them.

CLI

Every flag, every exit code, every environment variable.

Coverage

The 18 tools, 30 domains, 10 browsers and 3 token sources surface knows about.

Rust API

rustdoc for the crate, generated from the source on every docs build.

Stability

What is promised, what is not, and how a break is announced.

The one-screen version

surface              # scan, then open the dashboard
surface --json       # scan, print JSON, exit
surface --offline    # never touch the network
surface --check      # show resolved paths and settings, then exit

Config file	surface.toml in the config directory; every setting optional
State	usage-ledger.json and litellm-prices.json, state directory only
Env prefix	SURFACE_* — see CLI
Exit code	0 on a completed scan, including one that found nothing
Network	One optional request, for model prices

Machine-readable interfaces

Three things a script can depend on, each with its own stability note:

Surface	Documented in
The --json payload	JSON output
surface.toml keys	Configuration
reason strings (insufficient_privileges, no_history_database, tool_unavailable)	JSON output

How to read the Rust API reference

surface is a binary crate, so its modules are private and rustdoc is run with --document-private-items. What you get is the internals: the module-level docs carry the design reasoning and the measurements behind each decision, which is usually what you came for. None of it is a public library API — see Stability.