CLI documentation

Check Open Graph metadata in public URLs, local HTML files, and generated site directories with the same rules and report schema as the website.

Requires Node.js 20 or newer. npx downloads and runs the public @og-kit/cli package; the installed executable is named og-kit.

Quick start

No global installation is required. To pin a version for CI, add @og-kit/cli to devDependencies and run og-kit from your package script.

npx --yes @og-kit/cli check https://example.com
npx --yes @og-kit/cli check ./index.html --base-url https://example.com
npx --yes @og-kit/cli check ./dist --base-url https://example.com

Inputs

`Public URL`	`https://example.com`	Fetch and inspect one public page.
`HTML file`	`./index.html`	Inspect one local file. Add --base-url when tags contain relative URLs.
`Directory`	`./dist`	Recursively inspect HTML output and show a site-level summary.
`Multiple targets`	`./a.html ./b.html`	Inspect targets together with bounded concurrency.

Directory scans include **/*.html by default and ignore common dependency, VCS, and cache directories. Without --base-url, rules that require a public page identity are reported as skipped rather than passed.

Output formats

`human (default)`	Readable findings, skipped checks, scores, and directory summaries. Wording and layout are not a machine API.
`--json`	The stable core OgReport JSON schema.
`--sarif`	SARIF 2.1.0 for GitHub Code Scanning and compatible tools.
`--junit`	JUnit XML for CI test result panels.
`--quiet / -q`	Only human-readable findings; no headers or summary.
`--summary`	Only aggregate human-readable statistics.

Options

`--fail-on <error\|warn\|info>`	Lowest severity that fails the gate; default error, or config failOn.
`--concurrency <n>`	Maximum parallel targets; default 6.
`--config <path>`	Load a specific ogkit.config.json/js/mjs/cjs/ts file.
`--no-config`	Disable upward config discovery.
`--disable <id>`	Disable rule ids; repeat or use a comma-separated list.
`--only <id>`	Run only these rule ids; repeat or use a comma-separated list.
`--base-url <url>`	Public HTTP(S) base used to resolve page and asset URLs.
`--include <glob>`	Directory include glob; repeatable, default */.html.
`--ignore <glob>`	Additional directory ignore glob; repeatable.
`--baseline <path>`	Read a baseline whose matching findings do not fail CI.
`--update-baseline`	Write or refresh the selected baseline from this run.
`--no-color`	Disable ANSI color in human output.
`--lang <en\|zh>`	Set CLI language; OGKIT_LANG and then the POSIX locale are fallbacks.

Configuration

OGKit searches from the current directory toward the filesystem root. Unknown keys and invalid values fail loudly. Paths in a config are resolved relative to that config file.

// ogkit.config.mjs
export default {
  baseUrl: "https://example.com",
  include: ["**/*.html"],
  ignore: ["archive/**"],
  failOn: "warn",
  baseline: ".ogkit-baseline.json",
  rules: {
    "og-description-missing": "error",
    "description-too-short": "off"
  }
};

Adopt with a baseline

A baseline lets an existing project enforce no new regressions without hiding current findings from reports. First generate it, commit the JSON file, then keep using it in the gate.

og-kit check ./dist --base-url https://example.com \
  --baseline .ogkit-baseline.json --update-baseline

og-kit check ./dist --baseline .ogkit-baseline.json

Baseline matches suppress only the CI gate. The complete findings remain available in --json output. Re-run --update-baseline deliberately when accepted debt changes.

CI examples

Use a machine format for artifacts and the exit status for the gate. The examples below install the CLI as a pinned development dependency.

npm install --save-dev @og-kit/cli

{
  "scripts": {
    "check:og": "og-kit check ./dist --base-url https://example.com --fail-on warn",
    "check:og:sarif": "og-kit check ./dist --base-url https://example.com --sarif > ogkit.sarif"
  }
}

# GitHub Actions steps
- run: npm ci
- run: npm run check:og

Inline exceptions

Local HTML may carry a reviewed exception. A reason after -- is mandatory. Both forms currently apply to the document because not every finding has line information.

<!-- ogkit-disable og-description-missing -- landing page intentionally uses the title only -->
<!-- ogkit-disable-next-line description-too-short -- approved campaign copy -->

Exit codes

`0`	No finding at or above --fail-on after baseline matching.
`1`	One or more findings reached the gate severity.
`2`	Invalid arguments/config, input or I/O failure, or an unexpected tool failure.

Help and versions

The installed CLI is the authoritative reference for its release. --version prints the CLI, engine, ruleset, and report-schema versions on separate lines.

npx --yes @og-kit/cli check --help
npx --yes @og-kit/cli --version