Reference

CLI reference

The docsalive scan command, engine v0.2.1.

Usage

docsalive scan <target> [--execute] [--no-network] [--setup CMD]...
                         [--docs-dir DIR] [--include GLOB]... [--max-pages N]
                         [--parallel N] [--step-timeout SECONDS]
                         [--image IMAGE] [--runtime RUNTIME]
                         [--out DIR] [--keep-checkout]

<target> is a local directory or a Git URL. URLs are shallow-cloned into a temporary directory that is deleted when the command exits.

Options

Flag	Default	Description
`--execute`	off	Run planned blocks in sandbox containers. Without it, the scan only extracts and plans.
`--setup CMD`	none	Shell command run at the start of each page's container, e.g. installing your package. Repeatable.
`--no-network`	network on	Run containers with no network access.
`--docs-dir DIR`	auto	Override the detected docs directory.
`--include GLOB`	all pages	Only test pages matching the glob (relative to the repo root). Repeatable.
`--max-pages N`	0 (no limit)	Cap the number of pages.
`--parallel N`	4	Pages run concurrently.
`--step-timeout S`	60	Time limit per code block, in seconds.
`--image IMAGE`	runner image	Container image to run snippets in (Python 3.12 + Node 20 by default).
`--runtime RUNTIME`	docker default	Container runtime, e.g. `runsc` for gVisor.
`--out DIR`	none	Write `report.md` and `report.json` to this directory.
`--keep-checkout`	off	Keep the cloned repository instead of deleting it (local debugging only).

Outputs

report.json has three top-level keys: meta (engine version, target, commit, framework, pages, duration), summary (counts by status and category) and findings (one entry per code block):

{
  "spec_id": "docs/advanced/extensions.md:156",
  "page": "docs/advanced/extensions.md",
  "line": 156,
  "lang": "python",
  "status": "fail",
  "category": "api-drift",
  "reason": "snippet: parameter `extensions` is not accepted by the current API",
  "is_docs_bug": true
}

Entries also carry hint and evidence (an error excerpt of up to 700 characters). OpenAPI results appear under openapi.

Examples

# one section of a large docs site
docsalive scan . --execute --include "docs/quickstart*" --setup "pip install -q ."

# JavaScript package, installs from npm, so network stays on
docsalive scan ./my-js-tool --execute --setup "npm init -y >/dev/null && npm install my-js-tool"

# stronger isolation with gVisor
docsalive scan . --execute --runtime runsc --no-network

Environment

Fix drafting uses an OpenAI-compatible endpoint when one is configured. Without a key, the engine runs deterministic triage only.

Variable	Purpose
`DOCSALIVE_LLM_API_KEY`	API key for your model provider
`DOCSALIVE_LLM_BASE_URL`	OpenAI-compatible base URL
`DOCSALIVE_LLM_MODEL`	Model name