CLI Reference

Complete reference for the orino audit, orino fix, orino baseline, and orino init commands.

Commands

orino audit

Runs a full SEO and GEO audit against a project directory, a live URL, or both. Detects your framework automatically, collects data from codebase and live sources, runs all checks, and scores the result.

Flag	Type	Default	Description
--dir <path>	string	.	Project directory to audit
--url <url>	string	none	Live URL to run URL-based checks against
--framework <name>	string	none	Force framework detection instead of auto-detecting
--psi-key <key>	string	none	Google PageSpeed Insights API key
--pages <number>	number	0	Pages to audit beyond the homepage, sampled from the sitemap
--fail-on <level>	string	critical	Severity at or above which the run exits 1: critical, warning, or any
--baseline <path>	string	none	Baseline file — only findings not in the baseline trigger --fail-on
--no-url	boolean	none	Skip all live URL checks
--no-codebase	boolean	none	Skip all codebase analysis
--quiet	boolean	false	Print criticals and score summary only
--json	boolean	false	Output results as JSON to stdout
--output <path>	string	none	Write JSON output to a file (implies --json)
--report-txt [path]	string	./orino-report.txt	Export plain text report
--report-md [path]	string	./orino-report.md	Export Markdown report
--report-pdf [path]	string	./orino-report.pdf	Export PDF report
--sarif [path]	string	./orino.sarif	Write SARIF 2.1.0 for GitHub Code Scanning

Valid --framework values: nextjs-app-router, nextjs-pages-router, astro, sveltekit, nuxt, html.

Note

For --report-txt, --report-md, and --report-pdf, the Default column shows the output path used when no path argument is provided. All three flags are inactive by default.

Every audit flag can also be set in a config file. Flags always take priority over the config file, which takes priority over defaults.

orino fix

Creates the missing files Orino can generate safely from your route map: robots, sitemap, and llms.txt. It only ever creates files. An existing file is never modified or overwritten, so running it twice is harmless. Everything that needs judgement (titles, descriptions, schema) stays in the audit report.

npx orino-cli fix --url https://yoursite.com --dry-run
npx orino-cli fix --url https://yoursite.com

Flag	Type	Default	Description
--dir <path>	string	.	Project directory to fix
--url <url>	string	none	Site URL, used for absolute sitemap and llms.txt links
--no-url	boolean	none	Ignore any configured URL (sitemaps are then skipped)
--framework <name>	string	none	Force framework detection
--dry-run	boolean	false	Show what would be created without writing anything
--json	boolean	false	Output the fix plan as JSON

What gets created, by framework:

Framework	robots	sitemap	llms.txt
Next.js (App Router)	app/robots.ts	app/sitemap.ts	—
Next.js (Pages Router)	public/robots.txt	public/sitemap.xml	—
Astro	public/robots.txt	public/sitemap.xml	public/llms.txt
Nuxt	public/robots.txt	public/sitemap.xml	public/llms.txt
SvelteKit	static/robots.txt	static/sitemap.xml	static/llms.txt
HTML	robots.txt	sitemap.xml	llms.txt

Sitemaps list your static routes only. Dynamic routes such as /blog/[slug] can’t be known from the file system, so add those by hand (in sitemap.ts, fetch the slugs). A sitemap needs absolute URLs, so it is skipped when no site URL is known from --url, your config, or your environment. The generated llms.txt has a placeholder summary line: replace it before deploying.

The URL is only used to write links. orino fix doesn’t fetch anything and works offline.

orino baseline

Runs the same audit pipeline and writes the current findings to a baseline file, so a later audit can fail only on regressions. Always exits 0 on success — a baseline records the status quo, it does not judge it.

npx orino-cli baseline --output ./orino-baseline.json

Flag	Type	Default	Description
--dir <path>	string	.	Project directory to audit
--url <url>	string	none	Live URL to run URL-based checks against
--framework <name>	string	none	Force framework detection
--psi-key <key>	string	none	Google PageSpeed Insights API key
--pages <number>	number	0	Pages to audit beyond the homepage
--no-url	boolean	none	Skip all live URL checks
--no-codebase	boolean	none	Skip all codebase analysis
--output <path>	string	./orino-baseline.json	Baseline file to write

The baseline file records the check IDs of every current finding:

{
  "version": "0.3.0",
  "generatedAt": "2026-07-03T10:00:00Z",
  "url": "https://example.com",
  "findings": ["canonical-missing", "thin-content"]
}

See Baselines for how the comparison works.

orino init

Writes a fully commented orino.config.json template to the current directory, with every option documented inline. Refuses to overwrite an existing config (exits 1).

npx orino-cli init

See the Configuration reference for the full schema.

Environment variables

Variable	Description
ORINO_PSI_KEY	Google PageSpeed Insights API key. Equivalent to --psi-key. The flag takes priority when both are set.
CI	When set to any non-empty value, disables all interactive prompts. Set automatically by most CI providers.

Modes

Full mode (codebase + URL)

Requires a project directory (defaults to .) and a live URL passed via --url or detected from your project config. Runs every available check: framework-specific source analysis, live metadata, crawlability, structured data, PageSpeed Insights, and GEO readiness signals. Use this for the most thorough audit of a deployed site you have local access to.

Codebase only (--no-url)

Pass --no-url to skip all live URL checks. Orino analyses your source files, checking routing patterns, metadata exports, structured data definitions, internal link graph, and framework-specific conventions. PageSpeed Insights and live crawlability checks are skipped. Use this during local development before you have a deployed URL to test against.

URL only (--no-codebase or no local project)

Pass --no-codebase to skip all source file analysis, or run from a directory without a supported framework. Orino fetches the live URL and runs PageSpeed Insights, checks rendered metadata and Open Graph tags, validates robots.txt and sitemap, and checks GEO signals from the live page. Use this to audit sites where you do not have the source code.

Note

Passing --no-codebase without --url will trigger the URL prompt in interactive mode or exit with an error in non-interactive mode.

Multi-page auditing

By default Orino audits the homepage only. Pass --pages <number> to sample additional pages from your sitemap and run the full URL check suite on each — metadata, on-page, structured data, canonical, and internal-link checks.

npx orino-cli audit --url https://example.com --pages 25

• Selection. Pages linked from the homepage come first, then the remaining sitemap URLs in order. Non-HTML entries (.xml, .pdf, images) are excluded, and the homepage is always included regardless of the value.
• Cross-page checks. Duplicate titles and duplicate descriptions become real checks once more than one page is fetched. With a single page they skip rather than guess.
• Politeness. Pages are fetched in parallel in batches of five, with a two-second pause between batches and a sixty-second overall cap. Pages returning a non-200 status are logged as an info finding and skipped.
• Scoring and output. The score is calculated across every page combined. In --quiet mode a per-page summary table is printed, and every finding records which page it came from. The pagesAudited field in --json output reports the total.

Site-level checks — robots.txt, sitemap validity, PageSpeed Insights, codebase analysis, and GEO readiness — always run once, not per page.

Exit codes

Code	Meaning
0	Audit passed the threshold — no issues at or above the --fail-on level
1	Audit failed the threshold — issues found at or above the --fail-on level
2	Configuration error — invalid flags, a missing baseline file, a malformed config file, or no supported framework and no URL

The --fail-on <level> flag controls what counts as a failure: critical (the default), warning (critical or warning), or any. Because the default is critical, the default behaviour matches previous releases — a run with critical issues exits 1.

Exit codes apply in every output mode, including --json and --quiet, so a misconfigured CI job fails loudly with code 2 instead of reporting an empty perfect score.

Baselines

A baseline lets CI fail only on new issues rather than pre-existing ones — useful when adopting Orino on a site that already has findings you cannot fix immediately.

1. Record the current state once and commit it:

   npx orino-cli baseline --output ./orino-baseline.json

2. Pass it to future audits:

   npx orino-cli audit --url https://example.com --fail-on critical --baseline ./orino-baseline.json

A finding is treated as new when its check ID does not appear in the baseline’s findings array. Location is not compared — if the check ID was already known, it is not counted as a regression. Only new findings at or above the --fail-on level trigger exit code 1. The --json output reports the new findings in newFindings and sets baselineCompared to true.

CI/CD usage

Set CI=true (most providers do this automatically) and Orino disables all interactive prompts. Use --no-codebase with a deployed URL for post-deploy checks, or --no-url against your source during the build phase.

- name: Orino SEO Audit
  run: |
    npx --yes orino-cli audit \
      --url ${{ vars.SITE_URL }} \
      --fail-on critical \
      --json \
      --output orino-results.json
  env:
    ORINO_PSI_KEY: ${{ secrets.ORINO_PSI_KEY }}

Caution

Always pass --yes to npx in CI. GitHub Actions runners do not auto-confirm a first-time package install, so a bare npx orino-cli fails with orino: not found (exit 127). npx --yes installs non-interactively.

GitHub Action

The Orino repository is also a GitHub Action. It runs the audit and keeps one score comment up to date on each pull request (no new comment per push), listing the top critical and warning issues with links to their fix pages. It can also upload findings to Code Scanning so they appear as alerts on the affected files.

name: Orino

on: [pull_request]

permissions:
  contents: read
  pull-requests: write      # score comment
  security-events: write    # only needed with sarif: 'true'

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: tinotenda0/orino@v0.4.0
        with:
          url: ${{ vars.SITE_URL }}
          fail-on: critical
          sarif: 'true'
          psi-key: ${{ secrets.ORINO_PSI_KEY }}

Input	Default	Description
url	none	Live URL to audit. Empty runs a codebase-only audit
dir	.	Project directory, relative to the repository root
fail-on	critical	critical, warning, any, or never (report only)
pages	0	Pages to audit beyond the homepage
baseline	none	Baseline file. Only new findings count towards fail-on
psi-key	none	PageSpeed Insights key. Pass a secret
comment	true	Post and update the score comment on pull requests
sarif	false	Upload findings to Code Scanning
version	the action’s tag	CLI version to run. A v0.4.0 tag runs CLI 0.4.0; a branch runs latest

Outputs: score (0–100), exit-code, and results (path to the JSON results).

Permissions: the comment needs pull-requests: write, and sarif: 'true' needs security-events: write. The default GITHUB_TOKEN is read-only. Code Scanning is free on public repositories; private repositories need GitHub Advanced Security.

Findings without a file

Code Scanning only shows alerts attached to a file. Findings from live URL checks (such as a blocked crawler in the deployed robots.txt) and “file is missing” checks are anchored to package.json (or index.html / README.md), with the real location in the alert message.

Interactive prompts are also disabled when stdout is piped, so you do not need to set CI explicitly when using --json or --output.

JSON output fields

When --json is set, the output includes CI-oriented fields alongside the score and results:

Field	Type	Description
exitCode	number	The exit code the process will use (0, 1, or 2)
pagesAudited	number	Total pages audited — homepage plus any sampled with --pages
baselineCompared	boolean	Whether a baseline was supplied and compared
newFindings	string[]	Check IDs of findings not present in the baseline (empty when no baseline)

Help

npx orino-cli audit --help

Prints all available options to the terminal.