CLI reference

The private @shoalrun/cli package supplies the shoalrun command. It needs Node.js 22.12 or newer. Follow Getting started to install it from GitHub Packages, then run commands as npx --no-install shoalrun <command>. Framework contributors can build the source checkout and run node framework/dist/cli.js <command> from its root.

Commands that return data print JSON to standard output. On an error, the CLI prints {"status":"error","message":"..."} to standard error and exits with code 1. A config argument defaults to docs.config.yaml in the current directory unless noted.

Diagrams render without a browser: Pele handles Mermaid syntax, and D2 handles D2 source. Development installs include Puppeteer for browser UI tests; production package installs do not need it.

Start a project

init

shoalrun init [directory] [--starter minimal|api-docs]

Copies a bundled starter into directory (default .). minimal is the default; api-docs includes the fictional Cedar Parcel API, an overview and quickstart, a local OpenAPI file, generated references, search, and a color-mode toggle. Its README explains customization and deployment. Existing unrelated files stay in place, but any destination file collision stops the command before it copies anything. Existing destination directories must be real directories, not symlinks or files. The command prints JSON with the starter, absolute directory, copied files, and the next validate and build commands. Run those commands from the created directory, then replace fixture content and example domains. init does not install packages or deploy the site.

Build and serve

build

shoalrun build [config] [output] [--source-commit SHA] [--release-label LABEL]

Compiles the site. output defaults to site-dist. Prints { "status": "ok", "documents": <count>, "operations": <count> }.

The build writes to a temporary directory, then deletes output and replaces it. Don't point it at a directory with other files. The build stops before deleting anything if output contains the project or content directory, sits inside the content directory, or holds a file the build reads. It also writes the frontmatter reference to .shoalrun/ beside the config; add .shoalrun/ to .gitignore.

Every build writes /build-info.json with the build ID and resolved config digest. --source-commit adds a full 40- or 64-character Git commit hash; --release-label adds a short, public release name. The command uses only the values you pass. Neither flag selects a publication or deployment destination. See use Git branches for separate docs sites.

docs changes

shoalrun docs changes CURRENT-SNAPSHOT --since PREVIOUS-SNAPSHOT

Compares two local documents.sync.json files and prints JSON with build IDs, buildChanged, metadataChanged, and added, changed, and removed page records. Page identity includes its publication variant. The command validates both snapshots and rejects unsupported schema versions, invalid records, and duplicate identities. It reads files only; it does not fetch pages or modify a cache. Keep saved snapshots outside the replaced build directory. See incremental sync.

serve

shoalrun serve <site-directory> [--host HOST] [--port PORT]

Serves a built site. --host defaults to 127.0.0.1. The port comes from --port, then the PORT environment variable, then 8765. The server:

• Returns the Markdown twin when a request asks for text/markdown. See content negotiation.
• Applies redirects.json and the content types in resource-headers.json.
• Sends / to the home page when no page has the slug /: the page with ID guide.overview, then /reference, then the first page.
• Adds a trailing slash to page paths with a 301, and returns a plain-text 404 for missing files.

It serves plain HTTP with no compression or cache headers. To host it publicly, bind a public --host such as 0.0.0.0 and put a TLS proxy in front.

dev

shoalrun dev [config] [output] [--port PORT]

Builds the project, serves it at 127.0.0.1:8765 by default, watches the directory containing the config, and refreshes open pages after a successful rebuild. output defaults to site-dist; --port overrides PORT. A failed rebuild prints its error and keeps serving the last successful build. Fix the source to trigger another build. Restart the command after changing framework TypeScript or files outside the config directory. Also restart after editing a metadata.provider module or a custom highlighting module, because Node loads each module once.

search

shoalrun search <site-directory> <query> [--channel C] [--version V] [--language L] [--limit N]

Searches a built site's search-index.json without a server. Quote queries with spaces. It returns JSON with the selected publication, total matches, and up to eight ranked results by default. Each result includes a page ID, HTML URL, Markdown URL, title, summary, type, score, and a short body excerpt. A section match links to its heading in the HTML URL.

shoalrun search docs/dist "nullable response" --limit 5

If the index contains multiple publications, select one with --channel, --version, and --language. The CLI refuses to mix them. --limit accepts 1 through 100. Build with the default lexical search provider, or enable index: true for a custom provider. The command reports a missing index instead of rebuilding the site.

docs search and docs read

shoalrun docs search "configure navigation"
shoalrun docs read guide.navigation-lifecycle --json --max-tokens 4096
shoalrun docs search "search provider" --site docs/dist --limit 5

These commands use Shoalrun's bundled documentation by default. Pass --site DIRECTORY to search or read a built site's own documentation instead. docs search prints JSON results with document IDs and excerpts; docs read prints generated Markdown, or structured page data with --json. Both accept --max-tokens (default 4096; range 256–100000) and publication selectors --channel, --version, and --language. Search also accepts --limit (default 8; range 1–100). JSON results include budget metadata; plain Markdown reads report truncation on standard error. Increase the budget when a page is truncated. They need no project config, site build, browser, network, or agent-specific protocol. An agent can search for a task, read the matching page, and then run the ordinary project commands. The bundled docs are generated from this site's sources and checked against the self-doc build in the test suite.

docs mcp

shoalrun docs mcp
shoalrun docs mcp --site docs/dist

Starts a read-only MCP server over stdio. The default source is the bundled Shoalrun docs; --site selects a built site. The server exposes search_docs, get_page, get_outline, and get_section. They share the search/read core and token budgets with the CLI. Standard output is reserved for protocol messages. See connect an MCP client.

Documentation search/read errors use { "status": "error", "error": { "code": "...", "message": "..." } }. Codes distinguish invalid_input, unknown_page, missing_index, and internal_error. JSON mode sends errors to standard output and exits 1; plain reads send errors to standard error. Other commands retain the general CLI error shape described above.

eval prepare, eval check, eval snapshot, and eval compare

shoalrun eval prepare <site-directory> --tasks FILE --out REPORT
shoalrun eval check <site-directory> --tasks FILE --report REPORT
shoalrun eval snapshot <site-directory> > SNAPSHOT.json
shoalrun eval compare CURRENT.json --since PREVIOUS.json

prepare reads a YAML or JSON task file and writes a JSON report template for the built documentation. All tasks start skipped, runner details are unrecorded, and review is null. Existing report files are never overwritten. The command does not execute tasks or grade answers.

check validates a completed report against the current task definitions and built output. It prints JSON findings and outcomes, and exits 1 for stale reports, malformed data, invalid citations, incomplete judgments, or required tasks that did not pass. A missing report is a reported failure. Invalid tasks or an unreadable site fail before a report can be produced. See evaluate agent tasks for the schemas and audit hook.

snapshot prints a JSON file inventory and exact-output digest. compare validates two inventories and lists added, changed, and removed paths; it exits 1 when builds differ or inputs are invalid. These commands diagnose freshness without running or approving an evaluation. New report templates also include the inventory, so a stale report can show file differences in details.buildChanges.

vercel build

shoalrun vercel build [config] [output] [--source-commit SHA] [--release-label LABEL] [--chat]

Writes a Vercel Build Output API directory. output defaults to .vercel/output. It accepts the same public build provenance flags as build and includes /build-info.json in the static output. --chat adds the optional hosted chat function; the build fails if you request it and the function cannot be added. See Publish on Vercel and Host the chat on Vercel.

Author pages

scaffold

Short form, from inside a project:

shoalrun scaffold <template> -n <target-file> [options]

For example, shoalrun scaffold guide -n content/pagination.mdx uses the built-in guide template and derives the page ID guide.pagination.

Explicit form:

shoalrun scaffold <template> <config> <target-file> --id ID --title TITLE --summary SUMMARY --slug SLUG [options]

The short form finds docs.config.yaml in the current directory or a parent, and derives the ID, title, summary, and slug from the target path. --new is the same as -n.

The target must be a .md or .mdx file inside the content directory, and must not exist yet. The slug must start with /. The new page has draft access. Prints the template, page ID, file path, publication, and access. See templates for how values are derived.

docs context, docs plan, and docs apply

These commands support a reviewable edit to existing pages and loaded YAML config files:

shoalrun docs context guide.welcome [--config docs.config.yaml]
shoalrun docs plan --request-file edit-request.json --out edit-plan.json [--config docs.config.yaml]
shoalrun docs apply edit-plan.json [--config docs.config.yaml] --check
shoalrun docs apply edit-plan.json [--config docs.config.yaml]

docs context reports a stable page ID's authored sources and digests, navigation placements, relationships, and configuration owners. It also returns configured authoring directives and guide and exemplar paths. It does not return a generated API reference as an authored page.

The request file contains full replacement text for each existing file, relative to the project config directory:

{
  "edits": [
    { "file": "content/welcome.mdx", "content": "---\nid: guide.welcome\n...\n---\n\nRevised page text.\n" }
  ]
}

docs plan records the exact replacements and a SHA-256 digest of each original file. Each request edit can also include baseDigest, the lowercase SHA-256 digest of the UTF-8 source text used to write the candidate. If the current source differs, planning fails. Include this digest from the source your agent read before drafting. It refuses to overwrite an existing plan. The plan can be reviewed as JSON or with a diff tool. Edits can replace existing .md/.mdx files in the content directory and YAML files loaded by the config. Symlink targets and paths outside the project are rejected.

docs apply --check verifies the original digests, copies the project to a temporary directory, inserts the proposed text, and builds the candidate site. It reports affected published document IDs and routes without changing the source. Run docs apply without --check to repeat validation and write the files. A stale digest or failed build stops the write. The command does not run configured audit.tests, commit, deploy, or establish that technical claims are correct. Run shoalrun audit and review the rendered pages before publication.

ingredient draft and recipe draft

shoalrun ingredient draft --spec FILE --out FILE [--config FILE] [--check]
shoalrun recipe draft --spec FILE --out FILE [--config FILE] [--check]

ingredient draft takes a spec naming one explicitly configured API operation and a named inline request example. It copies the generated cURL request and first inline 2xx response example into a draft type: ingredient page. It supports outgoing requests in the default publication. recipe draft takes a project-owned spec with ordered ingredient file paths and assembles a draft type: recipe page for a customer goal. It rejects duplicate ingredient IDs and publication mismatches. Ingredients can declare workflow.inputs, workflow.outputs, workflow.prerequisites, and workflow.check; recipe specs can declare initial inputs and a final outcome. The assembler checks handoffs, rejects missing inputs and duplicate output names, and includes shared prerequisites once. Neither command executes a request or uses a model. See assemble recipes from ingredients for YAML fields and review workflow.

With --check, either command prints the proposed MDX and reports would-create, unchanged, or would-change; it writes nothing and does not build a preview. Without it, the command creates the output file and refuses to overwrite an existing one. A person or agent finishes and verifies the complete recipe before publication.

Inspect config and operations

These commands print configuration and API operation details for inspection.

operation inspect compiles the whole project without writing a site. When the operation isn't found in the selected publications, it prints "status": "missing-variant" and still exits with code 0. Put flags after the optional config path. An unknown or repeated flag fails before the project is compiled.

Audit a project and API sources

check

shoalrun check [config] [--json]

Run before pushing. Prints a readable PASS/FAIL summary; --json prints the structured audit report for CI. With no config argument, discovers docs.config.yaml in the current directory or a parent. Runs configured tests, local API checks, a temporary build, focused-contract checks, and local HTML and Markdown link checks. Exits with code 1 if a check fails. Existing site output is preserved. See local checks.

audit

shoalrun audit [config]

Runs the configured project audit, including enabled reference checks, focused contracts, test commands, and evaluation reports. Prints JSON and exits with code 1 when the audit fails. It does not call an authoring model or judge prose claims. See audit settings.

api audit

shoalrun api audit <openapi-file>

Renders every operation in an OpenAPI file. It checks that each operation has a unique operationId, that HTML field anchors are unique, and that every named example appears in both HTML and Markdown. Prints counts, sizes, and a failures list. Exits with code 1 when anything fails.

api import and api refresh

shoalrun api import https://api.example.com/openapi.yaml --output apis/remote
shoalrun api refresh apis/remote --output apis/remote-next

api import downloads an HTTPS OpenAPI document and its same-origin relative $ref files into a new local snapshot directory. It writes openapi.yaml, rewritten local references, and source-lock.json with each source URL and SHA-256 digest. Configure source: { kind: file, path: ./apis/remote/openapi.yaml } to build from the snapshot without a network request. api refresh downloads the same URLs again and reports added, removed, and changed files. If anything changed, it writes a complete new snapshot to --output and leaves the current one intact. Without --output, it chooses a digest-named sibling directory and reports that path. Point source.path to the new directory, run api review, and update publicReview.digest before a normal build. If nothing changed, no new directory is written.

Imports accept public HTTPS hosts on the standard port. Credentials, URL queries, redirects, cross-origin references, private network addresses, and oversized sources are rejected. A source that needs those features requires a separate, reviewed download into local files.

api focused-audit

shoalrun api focused-audit <site-directory>

Checks every focused contract in a built site. Each contract must:

• Be OpenAPI 3.0 or 3.1 with info.
• Contain exactly one operation, with an operationId.
• Use only internal #/components/ references that resolve, including discriminator mappings.
• Be linked from its page's Markdown twin. Prints the contract count, total and largest size, and failures. Exits with code 1 when anything fails.

api review

shoalrun api review <config-file> --output <local-directory>

Builds a local candidate without requiring the current publicReview.digest. Its JSON report lists each API's candidate digest, public pages, focused contracts, full-source downloads, and input hashes. Inspect the candidate for private material, then pin the digest in the API config. A normal build fails when the digest is missing or stale. Use a local output directory outside the repository; the candidate can contain sensitive material.

api materialize

shoalrun api materialize <api-id> <config> (--all | --operation ID | --route "METHOD /path")... [--output content/subdirectory]

Writes one-time draft MDX references from a registered local OpenAPI source. Repeat --operation and --route to select several endpoints; --all selects every endpoint and cannot be combined with selectors. --route uses an exact uppercase method and OpenAPI path. The default output is content/api/<api-id>/, and a custom output must stay inside the configured content directory. The JSON result lists written and skipped files. Existing matching pages are left untouched; conflicting files or unknown selectors stop the command. It does not alter config or navigation. See Generate and select API pages for the review and publishing workflow.

api select

shoalrun api select <api-id> <config> --output <selection-file>

Walks the default publication's OpenAPI operations and asks whether to generate a reference page for each. Answer y or yes, n or no, or press Enter to keep the current choice. q or quit cancels. Any other answer, or the end of input, cancels without writing. When every choice is made, it writes pathPrefix and an include list to the output file. See generate and select API pages.

npm scripts in this repository

npm run docs:format checks authored page formatting with the repository's Vale policy. npm run docs:lint runs the broader prose rules. npm run docs:check combines configured project checks, a temporary build, API audits, and local link checks. See formatting policy for customization.

Run the docs scripts from the repository root; run the framework build, demo, and preview scripts from framework/.

preview.mjs serves DOCS_PREVIEW_ROOT (default example/dist) on DOCS_PREVIEW_PORT (default 8765) at 127.0.0.1. It ignores PORT.

Preview a private OpenAPI file

npm run api-preview -- <openapi-file> <directory> (--all | <operationId>...) [--nav <layout.yaml>]

Generates a throwaway project in <directory> with one reference page per selected operation, then builds it to <directory>/site. It deletes and rewrites <directory>/content, so use an empty directory outside the repository. The script refuses a directory that has files unless an earlier run created it; each run leaves a .shoalrun-api-preview marker file. Serve the result with DOCS_PREVIEW_ROOT=<directory>/site node preview.mjs. The optional layout file groups operations in navigation; see navigation.

Search and chat

These commands are optional. They read a site you have already built, and a normal shoalrun build never runs them. See Search and chat for the distinctions between site search, passage retrieval, and answers.

index

shoalrun index <site-directory> [--embed [--config FILE] [--provider voyage|openai] [--model MODEL] [--dimension N] [--base-url URL] [--key-env NAME]]

Optional. Run it after shoalrun build. The build doesn't need it, and skipping it changes nothing about your site. It splits a built site into passages and writes ai/chunks.json in that directory. It reads documents.json, each page's Markdown twin, and search-index.json when present, and replaces any earlier file. It prints JSON with the page count, passage count, and output path. It fails when the directory has no documents.json, or when a page's Markdown path leaves the site directory.

Without --embed, the command makes no network requests. With --embed, it also sends each passage to an embedding API and writes ai/embeddings.json and ai/embeddings.bin. Shoalrun has no default provider or model. The retrieval.embeddings setting in your config chooses them. The command finds docs.config.yaml in the current directory or a parent, or you can name a file with --config. The flags override the config. Pass both --provider and --model and the command needs no config at all.

All embedding options need --embed. A rerun embeds only passages whose text changed. The JSON summary then adds an embeddings object with the model, dimension, and counts of embedded and reused passages.

See Passage index for the chunking rules and file formats.

serve --search

shoalrun serve <site-directory> --search --config docs.config.yaml [--port PORT]

Optional local preview for a custom browser search provider. Run shoalrun build and shoalrun index first. The server adds /__shoalrun/search, which returns page and section links from lexical passage retrieval or combines it with semantic retrieval when current vectors exist. It reads query embedding settings from retrieval.embeddings and the key from the environment. It runs only on a loopback address and accepts same-origin JSON requests. It does not add the chat panel or call a chat model. A site needs a custom provider to call the endpoint; the built-in search provider continues to use /search-index.json.

The local serve --search command is a preview server. The optional Vercel --chat build packages the same search handler as /__shoalrun/search, alongside /__shoalrun/ask, with shared rate and embedding budgets.

ask

shoalrun ask <site-directory> "<question>" [--config FILE] [--model MODEL] [--passages N] [--reader-view FACET=CHOICE[,CHOICE]]... [--channel C --version V --language L] [--no-rerank] [--no-direct] [--no-escalate] [--no-cards] [--json]

Optional. It answers one question from your built docs, with citations. It needs a site that you have run shoalrun index on, and a chat section in your config. The build doesn't need any of this, and skipping it changes nothing about your site. Quote the question.

The command searches the passages, using vector search too when the site has vectors, and optionally reorders the best results with Jev. Then it decides. If the docs don't cover the question, it says so and makes no call to the model. Otherwise it sends the best passages to the model and prints the answer, followed by a Sources list. Each source is a passage the answer cites, with a link. A citation to a passage that wasn't sent is removed, and an answer with no citation prints a warning on standard error. Text in the passages is treated as untrusted and can't instruct the model. Code that isn't in the passages, and sentences that the cited docs don't support, are listed as notes. See How an answer is checked.

Standard error also shows how the answer was made: the search mode, the decision, the Jev score, the model, the tokens, and the time. Any layer that failed, such as Jev or the query embedding, is listed as a note, and the answer falls back to plain search. --json prints the full result as JSON instead, including every passage the model saw and the support score of every checked sentence.

The command answers one question at a time. It reads OPENAI_API_KEY, or the variable that chat.keyEnv names, and JEV_API_KEY, or the variable that chat.rerank.keyEnv names, when you use a scorer. It fails with a clear message when the chat section, the chat key, or ai/chunks.json is missing. Without the scorer's key, the scorer counts as down, as chat settings explain.

answers

shoalrun answers <site-directory> --questions FILE [--config FILE] [--model MODEL] [--reader-view FACET=CHOICE[,CHOICE]]...

Optional. It builds answer cards from a list of questions and writes ai/answers.json. The list is YAML or JSON: plain strings, or mappings with question and aliases. It needs a site that you have indexed with --embed, and the same chat config as ask. This build step uses embeddings and the configured scorer. It calls the chat model for questions that pass the coverage gate. It never reuses a direct excerpt or another card. It embeds kept questions and aliases, then keeps only answers that passed every check. It prints JSON with the number of cards, the questions it skipped and why, and the output path. It replaces any earlier file, so keep the question list in your repository and rerun it after the docs change.

ask-log

shoalrun ask-log (<log-file> | --kv --config FILE [--days N]) [--min-repeats N] [--limit N] [--cards-out FILE] [--json]

Optional. It reads a log made by serve --ask --log and prints the report described in Keep a record of questions. --limit sets how many rows each list shows, and --json prints the full report as JSON.

chat

shoalrun chat pause|resume|status --config FILE

Optional. It switches a hosted chat off and on through the store that chat.budget.store names. See Turn the chat off.

serve --ask

shoalrun serve <site-directory> --ask [--config FILE] [--model MODEL] [--log FILE] [--public-preview] [--reader-view FACET=CHOICE[,CHOICE]]... [--port PORT]

Optional. It serves a built and indexed site with a local chat panel, so you can try shoalrun ask in a browser. An Ask button appears on every page, and the panel keeps the conversation so follow-up questions work. Each answer has a "How this answer was made" line with the search mode, the decision, the Jev score, the tokens, and the time. A sentence that fails the claims check, or code that isn't in the docs, appears under the answer as a warning.

--public-preview shows the reader-facing panel with the recording notice and a Turnstile check using Cloudflare's test keys. Answers still use your configured model and API credits; counters remain in memory.

This is a local preview and nothing more:

• It runs only on a loopback address (127.0.0.1, localhost, or ::1), because every question spends your API credits. It refuses --host 0.0.0.0 and any other address.
• serve --ask adds the panel and the /__shoalrun/ask endpoint for local preview. shoalrun vercel build --chat adds the hosted panel and function. Ordinary build and dev do not add chat.
• The endpoint refuses requests from other web sites and from unknown host names, requires JSON, caps the request size, and allows 20 questions a minute.

It reads the same chat and retrieval config as ask, and the keys from the environment. Stop it with the usual interrupt.

Working-tree authoring tools

docs project discovers pages, guidance, configuration, navigation, relationships, templates, and findings without selecting a page. docs source FILE reads bounded project-relative source passages. Both return JSON and accept --config FILE.

docs baseline --out FILE records the current working tree. docs validate checks a separate capture using a baseline or explicit file/page selectors. docs validation-status REPORT checks whether a retained result still applies. docs review REPORT presents that snapshot as JSON or Markdown. docs preview REPORT serves its exact build locally and returns a browser review URL plus affected HTML/Markdown URLs. These tools make no authoring provider calls and do not apply or publish edits.

See Authoring tools commands for selectors, budgets, artifact paths, statuses, and check execution limits. Follow Check working-tree documentation edits for a complete procedure. Existing context/plan/apply commands remain supported.

Related reading

Related topics

• Configuration reference — Build, serve, and inspect a config from the command line.