Skip to navigation
Reference

CLI commands and flags

This page documents every Doc Detective command and flag. The primary invocation is npx doc-detective.

Synopsis

npx doc-detective [command] [options]

A bare invocation with no command runs tests; the available commands are install, lsp, and debug. Use --version to print the installed version, and --help or -h to print usage. The CLI is strict: unknown flags cause an error instead of being ignored.

Run and global flags

These flags apply to the default run command. Each has a config-file equivalent; see Configuration precedence.

OptionAliasTypeDefaultDescription
--config-cstringPath to a config.json or config.yaml file.
--input-istring.Path to test specifications and documentation source files. May be paths to specific files or to directories to scan for files.
--output-ostring.Path of the directory in which to store the output of Doc Detective commands.
--logLevel-lstringinfoDetail level of logging events. Accepted values: silent, error, warning, info (default), debug
--allow-unsafebooleanAllow execution of potentially unsafe tests
--dry-run-nbooleanfalseResolve tests fully (file detection, inline-test extraction, config merge) and emit the resolved test plan as JSON, but do not execute any steps.
--reporters-rstring (array)["terminal","json","runFolder"]Reporters to use for output. Built-in reporters: terminal, json, html, runFolder (archives results in <output>/.doc-detective/runs/<runId>/, beside any screenshots from the run), junit (JUnit XML written as junit.xml in the output directory, or beside <output> when it names a file), markdown (a run summary written as doc-detective-summary.md in the output directory, or beside <output> when it names a file). Custom reporters registered via registerReporter() can also be referenced by name. Pass multiple values after the flag (e.g. —reporters terminal html) or repeat the flag (e.g. -r terminal -r html).
--test-tstringRun only tests whose testId matches the given regex (case-insensitive). Comma-separate multiple patterns; a test passes if any pattern matches.
--spec-sstringRun only specs whose specId matches the given regex (case-insensitive). Comma-separate multiple patterns; a spec passes if any pattern matches.
--hintsbooleantrueAfter a test run, show one applicable post-run hint with code samples and links. Some hints intentionally fire on failures (e.g. enableDebugLog). Disable with —no-hints.
--auto-screenshotbooleanfalseCapture a screenshot after every browser-based step. Images are saved in the per-run artifact folder (<output>/.doc-detective/runs/<runId>/) under the nested resource tree specs/<specId>/tests/<testId>/contexts/<contextId>/screenshots/, named with each step’s order, action, and ID, so the same step lands on the same relative path in every run’s folder for run-over-run comparison. Use —no-auto-screenshot to override a config file that enables it.
--auto-recordbooleanfalseRecord a video of every browser-based test context, in addition to any explicit record steps. The recording wraps the whole context and always uses the ffmpeg engine. Videos are saved in the per-run artifact folder (<output>/.doc-detective/runs/<runId>/) under the nested resource tree specs/<specId>/tests/<testId>/contexts/<contextId>/recordings/, so the same context lands on the same relative path in every run’s folder for run-over-run comparison. Use —no-auto-record to override a config file that enables it.
--auto-updatebooleantrueCheck the npm registry on startup for a newer doc-detective and self-update before running. Use —no-auto-update (or set autoUpdate: false in config) to pin to the installed version.
--cache-dirstringDirectory for lazy-installed runtime assets (heavy npm packages, browser binaries, ffmpeg). Defaults to <os.tmpdir()>/doc-detective/. Also overridable via DOC_DETECTIVE_CACHE_DIR.
--concurrent-runnersstring1Number of test contexts to run concurrently (default 1). Pass a number (for example, —concurrent-runners 4), or pass the flag with no value to use the CPU core count (capped at 4). With more than 1 runner, log lines from different contexts interleave and cross-context variable dependencies are unsupported.
--browser-fallbackstringautoHow to handle a context whose browser cannot start a driver session. auto (default): fall back to any other available browser (a fallback away from an explicitly requested browser reports WARNING). explicit: fall back only for auto-selected browsers; a broken explicitly-requested browser is skipped with a diagnostic reason. off: never fall back across browsers. Drivers are validated by execution, so a present-but-broken driver (e.g. a partially downloaded geckodriver) no longer silently skips coverage.
--shellstringbashDefault shell for runShell steps: bash (default), cmd, or powershell. cmd and powershell only work on Windows. Steps can override this value with their own shell field.
--exit-on-fail-ebooleanfalseExit with a non-zero code (1) when any spec’s result is FAIL, so a documentation-testing job fails the build like a broken unit test. Off by default: the CLI otherwise exits 0 on test failures (non-zero only on a crash or invalid config). WARNING results are non-fatal. Use —no-exit-on-fail to override a config file that enables it.

Negating boolean flags

Every boolean run flag has a --no- negation form; the ones you’ll typically reach for are: --no-hints, --no-auto-screenshot, --no-auto-record, --no-auto-update, and --no-exit-on-fail. (Other boolean flags, such as --dry-run and --allow-unsafe, can be negated the same way with --no-dry-run and --no-allow-unsafe.)

Notes on individual flags:

  • --reporters: see reporters and artifacts for the runFolder reporter and the built-in output formats.
  • --cache-dir: see the cache directory guidance.
  • --shell: runShell documents its steps, and shell selection covers how the default is chosen.
  • --dry-run: the resolved test plan is printed to stdout, so you can pipe it (for example, npx doc-detective --dry-run | jq).
  • --auto-update: skipped automatically when the CI environment variable is set, which GitHub Actions, GitLab CI, CircleCI, and most CI systems do—so CI pipelines usually don’t need --no-auto-update. To pin the version deterministically everywhere (including runners that don’t set CI), set autoUpdate: false in config or pass --no-auto-update.
  • --test and --spec: patterns match if they appear anywhere in the ID; anchor a pattern with ^ and $ to require an exact testId or specId match. Each value is split on commas before the parts are compiled as regexes, so a pattern can’t contain a literal comma (for example, --test "step{1,3}" is split into step{1 and 3}).

There is no flag to select the platform, browser, or headless mode for a run—those are contexts defined in your config (--browser-fallback only controls what happens when a selected browser can’t start). For containerized and headless runs, see Docker and headless runs.

Commands

Doc Detective runs tests when you invoke it without a command, and exposes named commands for setup, editor integration, and diagnostics.

Default (run tests)

With no command, doc-detective runs tests and takes no positional arguments; control its behavior with the flags in the Run and global flags section.

npx doc-detective --input ./docs

install

The install command group manages Doc Detective’s lazy-installed runtime assets—npm packages, browser binaries, ffmpeg, agent tools, and mobile toolchains. Its subcommands are agents, runtime, browsers, bash, android, ios, status, and all. For every subcommand, option, and example, see the install reference.

lsp

Start the Doc Detective language server (LSP) over stdio for editors and AI agents. It also ships as a standalone command, doc-detective-lsp.

This is distinct from install agents: the language server (lsp) exposes editor and AI-agent integrations over the LSP protocol, while install agents installs the Agent Skills and slash commands documented in the agent tools overview.

OptionTypeDefaultDescription
--stdiobooleantrueCommunicate over stdio (the only supported transport). Present for explicitness and editor configs.
npx doc-detective lsp

debug

Print diagnostic information about the runtime environment (OS, Doc Detective version, tool versions, browsers, referenced env vars) and exit without running tests.

OptionTypeDefaultDescription
--include-envbooleanfalseAlso dump the full process.env (redacted by name and value shape). Off by default to avoid leaking PaaS-injected credentials (DATABASE_URL, Sentry DSN, webhooks).
npx doc-detective debug --include-env

Exit codes

The standalone doc-detective CLI does not exit with a non-zero code when tests fail—it exits non-zero only on a crash or invalid configuration. To gate CI on test failures, parse the results summary from the reporter output (the JSON reporter), or use the GitHub Action’s exit-on-fail behavior.

The default json reporter writes a testResults-<timestamp>.json file into the --output directory (it prints the path as See detailed results at …); read that file’s summary to decide whether the run passed. The debug command exits non-zero when it finds an invalid configuration. The specific non-zero value isn’t a stable contract, so gate CI on the parsed results, not on which non-zero code the process returns.

Configuration

Config auto-discovery

When you omit --config, the CLI looks for a config file in the current directory in this order: .doc-detective.json, then .doc-detective.yaml, then .doc-detective.yml. If none exists, it runs with defaults. When you pass --config, that path is authoritative—a mistyped path fails rather than falling back.

Configuration precedence

Doc Detective merges configuration in this order:

  1. File config and the DOC_DETECTIVE_CONFIG environment variable (the environment value merges over the file).
  2. Validation against the config_v3 schema.
  3. CLI flag overrides.
  4. Runtime: the runner and reporters read only the merged config.

CLI flags override the validated config; they don’t bypass it, and every flag maps to a camelCase config key.

Invocation

  • npx doc-detective ... is the primary invocation.
  • Global or local install: install with npm, then call doc-detective .... See installation.
  • Docker: the images use the entrypoint npx doc-detective, so docker run <image> --input ... passes flags straight to the default run command. See Docker and headless runs.

Examples

Run tests over a directory:

npx doc-detective --input ./docs

Preview the resolved plan without running:

npx doc-detective --input ./docs --dry-run

Run a filtered subset with specific reporters:

npx doc-detective --input ./docs --test "smoke" --reporters terminal json

Start the language server:

npx doc-detective lsp