Saylent

CLI reference

Every command, every flag, the run bundle, and where config comes from.

saylent <command> [options]. Every command that spends money prints an estimate and asks to confirm before it spends (skip the prompt with --yes). Run any command with --help for this same reference in the terminal.

saylent demo

Renders the bundled sample run (Kestrel Uptime, a fictional product we host, audited by a real smoke run on 2026-09-10) into report.html, report.md and run.json. No key, no network, no cost; it never reads a key.

FlagWhat it does
--out <dir>Output directory (default: ./saylent-demo)
--openOpen report.html in your default browser afterwards

The folder it writes is an ordinary run folder, so saylent report and saylent history work on it like on a real audit's output.

saylent audit <domain>

Runs a full audit and writes run.json, report.html, and report.md.

FlagWhat it does
--brand <name>Brand name (default: the domain)
--competitors <a,b>Comma-separated competitor domains or names
--profile <profile>smoke (default, 6 questions) or full (23 questions). Overrides AUDIT_PROFILE and saylent.config profile
--engines <a,b>Comma-separated: chatgpt,claude,gemini,perplexity, or an answer surface (google_ai_overview,google_ai_mode,copilot). Overrides AUDIT_ENGINES and saylent.config engines. An unknown name is refused with a sentence, never silently dropped
--surfaces <a,b>Answer surfaces to ADD to the engines: google_ai_overview,google_ai_mode,copilot. Read through your own SerpApi key (SERPAPI_API_KEY; saylent keys set serpapi), billed per search by your SerpApi plan. Google shows an AI Overview for some queries only; the rest are recorded "not shown". See Answer surfaces
--country <cc>Two-letter country the surfaces answer for (e.g. us, de). Language follows --locale. Surfaces only
--location <city>City-level location for the Google surfaces, e.g. "Austin, Texas, United States". Surfaces only
--questions <file>Reuse a frozen question set - a previous run.json, a questions.json from saylent questions, or a plain text file (one question per line)
--samples <n>How many times each scored question is asked (1-5, default from the profile). Overrides AUDIT_SAMPLES and saylent.config sampling
--skip <a,b>Skip costly stages: drafts,corpus,gates. drafts = no drafter LLM calls (fixes list without artifacts). corpus = no cited-page fetches (citation presence unverified). gates = no site checks (never reported as a pass). Overrides AUDIT_SKIP and saylent.config skip
--judge <model>Judge model; its provider family is inferred from the name
--judge-family <fam>anthropic | openai, when the judge model name is ambiguous
--model <role>=<model>Repeatable. role: brand, drafter, chatgpt, claude, gemini, perplexity
--out <dir>Output directory (default: ./<domain>/<YYYY-MM-DD>/)
--format <a,b>Which files to write: md,html,json (default: all three)
--yesSkip the "Run it?" confirmation
--dry-runPrint the preflight block, judge mode, and the questions it would ask (template defaults, $0, no crawl), spend nothing, exit 0
--no-brand-modelNo further effect on audit - --dry-run already always previews with template defaults; documented for parity with saylent questions
--max-usd <n>Refuse to run if the high estimate exceeds this
--user-agent <string>Override the crawler's User-Agent (default: SaylentAudit/<version> (+docs url), or saylent.config userAgent). Applies to the whole run's fetches - crawl, corpus, domain checks
--max-pages <n>Cap how many crawled pages feed the brand model and corpus (1-200; default: the profile's own budget)
--allow-privateAllow the audited site's own host (and its www/apex sibling) to resolve to a private/internal address - for a staging server on your own network. Never on by default; prints a warning
--locale <bcp47>Translate the generated question set into this language once (e.g. de, pt-BR), via the drafter model. No effect with --questions (a reused set is never regenerated)

Exit codes: 0 every engine answered, 1 the run failed outright or no engine has a usable key, 2 the run completed but at least one requested engine had a failed answer (the report says which, and scores from the answers that came back). A surface question that was not shown is a recorded gap, not a failure, and does not change the exit code.

A surface asked for without a SerpApi key is refused by name before anything is spent, and --dry-run says so on its Surfaces line. When the run asks a surface, the preflight prints that line with the provider, the locale and the price per search.

The finish summary ends with two lines from Sources & opportunities: Sources (citations, domains and the most cited domain) and Off-site (how many off-site opportunities, and the first one).

saylent verify <run.json>

Re-asks the exact same frozen question set from a baseline run, against the same engines, and writes a movement report instead of a fresh one.

FlagWhat it does
--samples <n>Frozen questions already carry their own effective count and are reused as-is; this only decides whether a resolved-default mismatch against the baseline is allowed to proceed (pass the baseline's own count, or a new one, explicitly)
--skip <a,b>Accepted for parity with audit, but has no effect here: a verify never drafts artifacts, fetches your site's corpus, or checks site gates regardless
--judge <model>Judge model; its provider family is inferred from the name
--judge-family <fam>anthropic | openai, when the judge model name is ambiguous
--model <role>=<model>Repeatable. role: brand, drafter, chatgpt, claude, gemini, perplexity
--yesSkip the confirmation
--max-usd <n>Refuse to run if the estimate exceeds this
--notify <a,b>When the run finishes, send what changed vs the baseline to slack, webhook and/or email (targets from SAYLENT_* variables; see Alerts). Nothing changed, nothing sent
--notify-alwaysSend even when nothing changed
--notify-allow-loopbackLet the webhook or Slack URL point at this machine (localhost, 127.0.0.1, ::1; http allowed), for testing a local receiver. Off by default; other private addresses are always refused (Alerts)
--user-agent, --max-pages, --allow-private, --localeAccepted for parity with audit, but have no effect here: verify re-asks the same frozen questions and never crawls, fetches your site's corpus, or generates a new question set

Writes a new run.json (kind: "verify") and movement.html into a sibling dated directory next to the baseline's own, so re-verifying never overwrites what it compares against. Exit codes match audit: 0 / 1 / 2.

Verify refuses to run when the question templates or the resolved sample count have changed since the baseline was frozen, rather than silently comparing two different question sets. A baseline that asked an answer surface needs the SerpApi key again, and is read from the baseline's own locale. Verify and history is the walkthrough: what it reuses, what makes it refuse, what the movement report says, and how to keep re-checking on a schedule.

saylent gate-check <domain> (alias saylent check)

The command that runs the site check. No keys, no LLM calls, $0. It crawls a handful of pages and reports what AI bots can actually reach:

Saylent · gate-check · example.com

  robots.txt   training: GPTBot allowed · ClaudeBot allowed
               search:   OAI-SearchBot allowed · PerplexityBot allowed
               user:     ChatGPT-User allowed · Claude-User allowed
  live probe   GPTBot 200 · ClaudeBot 403 ⚠ (robots allows -> CDN/WAF override)
  JSON-LD      Organization ✓ · Product ✗
  meta         noai: absent ✓ · noindex: absent ✓
  Result       WARN · 1 blocked-at-CDN · 1 missing schema      (4.8s, $0)

The three bot classes: training crawlers (GPTBot, ClaudeBot) build model weights, not citations - blocking them is a legitimate choice and only warns. Search-index crawlers (OAI-SearchBot, PerplexityBot, and friends) and user-fetch agents (ChatGPT-User, Claude-User) feed live answers directly - blocking either one fails the check. A page allowed by robots.txt that still returns 401/403/429 to the live probe means a CDN or WAF is overriding robots.txt, and the line says so.

Exit codes: 0 on pass or warn only, 1 if a check failed, 2 if the site could not be reached at all, so a typo'd domain can never sit in CI as a permanently green check. Wire it into CI to fail a deploy that regresses AI-bot access.

saylent report <run.json>

Re-renders report.html / report.md from an existing bundle. No network, no LLM call, $0. Useful after hand-editing a bundle, or re-rendering with a newer @saylent/report version.

FlagWhat it does
--format <a,b>md,html (default: both)
--out <dir>Output directory (default: alongside the input file)

saylent sources <run.json> [more run.json...]

Where an audit's answers come from, with receipts: off-site opportunities, citation share by domain per engine and surface, and who the answers name. It reads the bundle only - no network, no model call, $0. Two or more bundles of the same brand print the history instead. The definitions are on Sources & opportunities.

FlagWhat it does
--view <name>summary, opportunities, domains, voice or all (default: all, as text)
--engine <id>Only rows cited by this engine or surface
--type <type>Only domains of this type: own_site, rival_site, review_site, forum, docs, news, marketplace, reference, video, social, editorial, other
--domain <host>One domain: its pages and every answer citing it
--limit <n>Rows per list (default 10, max 50)
--jsonPrint the same JSON the MCP sources tool returns

saylent crawlers <logfile|dir|->

Which AI crawlers actually visit your site, from your own access log: requests per bot and purpose (training, search index, user-triggered fetch), the pages they fetched, and the requests that were blocked or failed, with redacted log lines as receipts. Reads nginx/Apache combined, Vercel log drains and Cloudflare Logpush; .gz and directories too. $0; the log never leaves your machine. AI crawlers has the bot registry and every rule.

FlagWhat it does
--run <run.json>Join with an audit: the cited pages of your site no AI crawler fetched in the log window
--verify-ipsCheck IPs against the operators' published ranges (downloads those public lists, cached 24 hours)
--since <date>, --until <date>An ISO date window
--bot <id>One bot, e.g. gptbot
--show-ipsKeep client IPs in the receipts (redacted by default)
--limit <n>Rows per list (default 10, max 50)
--out <dir>Write crawlers.json and crawlers.md
--jsonPrint the full report

saylent export <run.json|dir> [more...]

Your data as CSV or JSON: runs, answers, citations, sources, opportunities, share_of_voice, fixes, search_queries and, with --crawlers, crawlers. The columns are versioned (saylent.export/v1) and every one is documented on Export and API. $0; it reads files only. A folder is one run (it holds run.json) or a brand's history (<YYYY-MM-DD>/run.json).

FlagWhat it does
--format <csv|json>csv (default): one <table>.csv per table. json: one export.json
--out <dir>Where to write (default ./saylent-export)
--table <name>Only this table
--crawlers <file>Add a crawlers.json from saylent crawlers --out
--stdoutPrint instead of writing (CSV needs --table)

saylent fixes <run.json>

The fixes a run drafted, ranked, with the evidence behind each, $0. --fix <key> prints one fix with its full drafted artifact; --json prints the MCP fixes tool's payload.

saylent fixes apply <run.json> --repo <path>

Writes the site-side fixes into your own site repository, on a new branch:

  • robots.txt: the drafted groups for the AI crawlers a run found refused. A missing bot is appended; a group that names only that bot has its rules replaced; a group shared with other bots is left alone and listed for review. If robots.txt is generated (for example app/robots.ts), the rules go in a file beside the snippets for you to move by hand.
  • JSON-LD: each drafted block becomes a snippet file under saylent-fixes/jsonld/, with where it goes. Saylent never edits your templates.
  • saylent-fixes/PULL_REQUEST.md: the receipts behind each change, a review checklist (every TODO-VERIFY value), the fixes not applied, and how to verify after the deploy.

It refuses a folder that is not the root of a git repository, a work tree with uncommitted changes, and any path that resolves outside the repository. It shows the diff and asks before writing, commits on the new branch with your own git identity, and never pushes: it prints the git push and gh pr create commands for you. Saylent drafts no llms.txt, so none is written.

FlagWhat it does
--repo <path>The site repository root (required)
--only <a,b>Only these fix keys (from saylent fixes)
--dir <name>Folder for the snippets and PULL_REQUEST.md (default saylent-fixes)
--branch <name>The branch to create (default saylent/fixes-<date>)
--dry-runShow the diff and stop
--yesApply without the prompt (needed when stdin is not a terminal)

saylent history <dir>

Lists past runs found in <dir>/<YYYY-MM-DD>/run.json:

  2026-09-09  smoke  mentioned 2 of 6  ·  recommended 0 of 6   $0.51
  2026-09-16  verify mentioned 5 of 6  ·  recommended 2 of 6   $0.44   ▲
FlagWhat it does
--digestThe weekly digest: what changed between the newest run and the newest one at least --days older (recommendations gained or lost, new rivals, new off-site opportunities). $0
--days <n>The digest window (default 7)
--notify <a,b>Send the digest to slack, webhook and/or email (Alerts)
--notify-allow-loopbackAs on verify: allow a webhook or Slack URL on this machine
--jsonPrint the digest payload (saylent.alert/v1)

saylent keys

SubcommandWhat it does
saylent keys listList configured providers, masked, with the source each came from
saylent keys set <provider>Set one key interactively (openai, anthropic, gemini, perplexity, or serpapi). serpapi unlocks the answer surfaces
saylent keys testVerify every configured key with a free call. The SerpApi check uses its free Account API, which does not count against your searches
saylent keys remove <provider>Remove a stored key

Keys resolve in order - environment variable → .env in the current folder → ~/.saylent/config.json - and a later source never overrides an earlier one that already has a value. Keys are never printed, never written into run.json or any report, and every error message the CLI prints has known key values scrubbed out first. There's no --openai-key flag on purpose: a key on the command line ends up in your shell history.

saylent questions <domain>

Prints the buyer questions an audit would ask, and writes them to a file you can edit by hand before spending anything on answers.

FlagWhat it does
--brand <name>Brand name (default: the domain)
--competitors <a,b>Comma-separated competitors
--profile <profile>Which profile's sampling line to print: smoke (default) or full. The printed library is the full one either way
--out <file>Where to write the set (default: ./questions.json)
--no-brand-modelSkip the crawl and brand-model call - generate from the template defaults and the domain name. $0, no keys.
--printPrint only, write no file
--yesSkip the confirmation

Cost: one brand-model call (about $0.02 of your credits, plus a free crawl) unless you pass --no-brand-model, which is $0 and needs no keys at all.

Questions and models is the walkthrough: the shape of the file it writes, how to add, remove and retag a row, what a per-row samples value does, and the three file shapes --questions accepts (a previous run.json, a questions.json, or one question per line in a text file).

saylent questions import <file>

Real questions in: a Google Search Console Queries export, any CSV (--column) or text lines, into a questions.json that audit --questions asks verbatim. $0 and offline; every dropped row is counted by reason. Import questions has every rule.

FlagWhat it does
--out <file>, --forceWhere to write (default ./questions.json); --force overwrites
--format <f>gsc, csv or text (default: detected)
--column <name|n>, --weight-column <c>CSV: the question column, and a numeric column to rank by
--min-impressions <n>Search Console: drop rarer queries
--exclude <regex>, --include <regex>Drop or keep matching rows (repeatable)
--questions-onlyKeep question-shaped rows
--clusterMerge near-identical queries
--max <n>How many to keep (default 20, max 50)
--type <type>The type every row gets (default custom)
--language <tag>, --country <cc>The set's locale: the answer surfaces' default
--rewrite, --yesRewrite queries as natural questions with your drafter model, after the estimate
--preview, --jsonPrint instead of writing

Only category and problem rows are scored and count toward the recommended band. Every other type - custom included - is asked, judged and reported in full, and deliberately left out of the band, so nothing you add by hand can inflate your own score.

saylent models

Read-only, $0, no network: prints the model registry exactly as it resolves for the keys, config, and environment on this machine right now - which model serves which role, and whether that choice came from a flag, an env var, saylent.config models, or the shipped default. Also shows which model would judge each engine's answers, and warns if a judge would be the same model that answered (self-judging, not an independent check).

The judge is set with --judge (plus --judge-family when the model name does not say which provider it belongs to); --model <role>=<id> takes one of six roles - brand, drafter, chatgpt, claude, gemini, perplexity. There is no judge role on --model. What each role does, and the examples: Questions and models.

Precedence: --judge / --model role=id flag → MODEL_* env var → saylent.config models → the shipped registry default.

saylent mcp

Serves the same pipeline over the Model Context Protocol on stdio, so an agent can run an audit itself. No flags: everything is set by the environment it is started with.

ToolWhat it doesCost
auditFull audit of a domain. Writes run.json, report.html, report.md; returns the verdict, the band, the summary blocks, the file paths and the real costYour own credits
verifyRe-asks an existing run's frozen questions and writes movement.htmlYour own credits
gate_checkAI-bot access for a site: robots.txt per bot class, a live per-user-agent probe, JSON-LD, meta directives$0
read_reportThe summary blocks of a run.json already on disk, whole or one named section$0
sourcesCitation share, share of voice and off-site opportunities of a run.json, with receipts$0
fixesThe drafted fixes of a run.json, with their evidence$0
historyTwo or more runs of one brand: what moved, with receipts$0
exportThe export tables, inline or as files$0
crawlersWhich AI crawlers visit, from an access log$0
questions_importPreview a question import; writes nothing$0

audit and verify take the same arguments the flags above take, from one shared schema - so the two surfaces can never drift. Each tool states its own cost range in its description, and the estimate is checked against max_usd and the daily spend cap before anything reaches a provider.

Three things the MCP server refuses that the CLI allows, because an agent - not a human - picks the arguments and the working directory:

Environment switchDefault (unset)Set to 1
SAYLENT_MCP_ALLOW_PRIVATEallow_private is refused; the private-network guard stays onallow_private is honored, as on the CLI
SAYLENT_MCP_ALLOW_ANY_OUT_DIRAn out_dir outside the server's own working directory is refusedAny out_dir is allowed
SAYLENT_MCP_ALLOW_EXEC_CONFIGOnly saylent.config.json is loaded; .js/.mjs/.ts (which execute on load) are ignored, with a log line saying soExecutable config files are loaded too

Provider keys are read from the environment, a .env, or ~/.saylent/config.json exactly as they are for the CLI, and can never be passed as tool arguments. Full setup - the client config block for Claude Desktop and other MCP clients, and the argument table - is on The MCP server.

The run bundle (run.json)

run.json is the lossless format every command reads and writes - BUNDLE_VERSION: 1. Top-level keys: version, run (id, kind, profile, status, brand, the frozen engine set, the model used per role, judge mode, timings, cost, skip - which stages this run skipped, if any - and surfaces, the SERP provider and locale when the run asked an answer surface), brand_model, questions (the frozen set), answers (every raw answer text and every sampled draw, not just the final verdict), citations, corpus_pages, domain_checks, fixes, scores, health, and sources (Sources & opportunities, optional: a bundle without it is read unchanged). Nothing is summarized or dropped - this is also what a downloaded bundle from the full app looks like (GET /api/runs/<id>/export?format=bundle), so a CLI run and an app run produce the same artifact. Compatibility is additive only: a bundle with a different version is refused rather than guessed at.

Configuration

Drop a saylent.config.json (or .js / .mjs / .ts, in that priority order when more than one exists) in the folder you run from. Every field is optional; an absent file means the shipped defaults. Precedence for any overlapping value: CLI flag → environment variable → saylent.config.* → shipped default.

See Configuration reference for the complete file with every field, its default, and one table of where each control lives on the CLI, in the environment, in the config file and in the app.

Environment variables (CLI tier)

VariableWhat it does
OPENAI_API_KEYRequired (one of the two)
ANTHROPIC_API_KEYRequired (one of the two)
GEMINI_API_KEYOptional, adds the Gemini engine
PERPLEXITY_API_KEYOptional, adds the Perplexity engine
SERPAPI_API_KEYOptional, unlocks the answer surfaces (Google AI Overviews, Google AI Mode, Microsoft Copilot)
AUDIT_PROFILEDefault --profile (smoke/full) when the flag isn't passed - overrides saylent.config profile
AUDIT_ENGINESDefault --engines list when the flag isn't passed - overrides saylent.config engines
AUDIT_SAMPLESDefault --samples value (1-5) when the flag isn't passed - overrides saylent.config sampling and the profile default
AUDIT_SKIPDefault --skip value (drafts,corpus,gates) when the flag isn't passed - overrides saylent.config skip
SAYLENT_USER_AGENTOverride the crawler's own User-Agent string
SAYLENT_APP_DOMAINYour domain, appended to the diagnostic UA the live per-bot probe sends
DAILY_SPEND_CAP_USDLocal daily spend ceiling (default 20)
MODEL_*Model registry overrides - see saylent models above and Configuration
SAYLENT_SLACK_WEBHOOK_URL, SAYLENT_WEBHOOK_URL, SAYLENT_WEBHOOK_SECRETTargets for --notify slack / webhook; the secret signs webhook requests (Alerts)
SAYLENT_SMTP_URL, SAYLENT_ALERT_EMAIL_FROM, SAYLENT_ALERT_EMAIL_TOTarget for --notify email: smtps://user:pass@host:465 or smtp://...:587 with STARTTLS

Every one of these (except the alert targets, which are the only place those settings live) is a DEFAULT: the matching flag always wins, and a bad value is refused with the exact variable name and what was expected, never silently ignored.

On this page