CLI and config file

The ondocs command has four subcommands: index builds or checks the index, init writes the endpoint for your host, dev serves the endpoint on your machine, and eval scores retrieval against questions whose answers you know. Run them with npx ondocs, or from a package.json script.

#ondocs index

ondocs index [dir] [options] builds ask-index.json from the Markdown, MDX and HTML files in dir.

#Choosing the embedding model

Without --embedding, the CLI uses openai:text-embedding-3-small when OPENAI_API_KEY is set, or openai/text-embedding-3-small through AI Gateway when only AI_GATEWAY_API_KEY is. With neither, it fails rather than quietly building a keyword-only index, and suggests -e mock to try it without a key. -e none builds a keyword-only index on purpose. -e workers-ai:@cf/baai/bge-small-en-v1.5 embeds with Workers AI over Cloudflare's REST API, with CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN, for the Workers AI Worker; its vector size is fixed, so --dimensions does not apply.

#Environment and exit codes

The CLI reads .env and .env.local from the working directory, without overriding variables that are already set. It exits with 0 on success, 1 when the build fails or --check finds the index stale, and 2 on a usage error.

#ondocs init

ondocs init [options] writes the ask endpoint and the MCP endpoint for the site in the working directory and the host it deploys to: Vercel, Netlify, Cloudflare (Pages, or a Worker with static assets) or GitHub Pages, whose endpoint is a Cloudflare Worker of its own. It detects the site from its config (Docusaurus, Starlight, Astro, Next.js, VitePress, Hugo, MkDocs, Jekyll or Eleventy) and the host from vercel.json, netlify.toml, a wrangler config or a GitHub Pages workflow, and asks for the host when it cannot tell. Deploying shows what it writes for each.

It prints each file it created, updated or left unchanged, the environment variables to set and where, and the steps left: the packages to install, the dialog to add and the deploy. It exits with 0 when everything is written, 1 when it left a file as it was or an edit for you to make by hand, and 2 on a usage error. It reads no .env file and no credential, and it deploys nothing. An Astro site with an SSR adapter gets no file: its integration serves the endpoints.

#ondocs dev

ondocs dev [options] serves POST /api/ask on 127.0.0.1, answering from a built index, for the dialog on your site's dev server. It serves the same index as an MCP server at /api/mcp, keyword-only, for your editor's agent.

It embeds questions with the model the index records, answers with OpenAI when OPENAI_API_KEY is set and with the mock model otherwise, and reloads the index when the file changes. It only answers pages on this machine (localhost, 127.0.0.1 and [::1] origins, on any port) and requests addressed to localhost, so a site you visit cannot spend your key through it, and it caps request bodies at 64 KiB. Try it locally shows it with each integration.

#ondocs eval

ondocs eval <questions.yaml> [options] scores retrieval against a file of questions with the pages that answer them, and questions marked unanswerable: hit@1, hit@3, refusal precision and refusal recall, question by question. It exits 1 when a score is under its threshold. Measure and improve answers has the file's format.

It embeds each question with the model the index records, as ondocs dev does, and calls no language model. It loads .env and .env.local like index, and exits 2 on a usage error or a file it cannot read.

#The config file

For an embedding provider the specs don't cover, or content that is not on disk, pass a config module with --config. Every field is optional:

// ondocs.config.mjs
import { cohere } from '@ai-sdk/cohere';
import { getPosts } from './lib/cms.mjs';

/** @type {import('ondocs/node').AskConfig} */
export default {
  embeddingModel: cohere.embedding('embed-multilingual-v3.0'),
  baseUrl: '/docs',
  documents: async () =>
    (await getPosts()).map((post) => ({
      id: post.slug,
      url: `/blog/${post.slug}`,
      title: post.title,
      content: post.markdown,
    })),
};

defineConfig from ondocs/node types the object without a JSDoc comment. Share the config with your route handler, as the ondocs website does, so the index and the queries always use the same embedding model.