CLI reference

lv24-seo is the command-line surface of the engine. It treats provider data as read-only by default, prints one machine-readable envelope with --json, and changes provider state only through three explicitly gated write commands. The same executable runs on Windows, macOS and Linux.

Command table

The table is filterable by command, group or description. Command names and flags are identical in every locale; only the surrounding documentation is translated.

Filter commands

Start 5

Command	Description	Copy
lv24-seo version --json	Print the engine version and package name.
lv24-seo doctor --json	Offline check of Python, config, data directory and token presence; no network calls.
lv24-seo init --property https://example.com --data-dir ./data	Write a commented seo.toml and the data directory; refuses to overwrite without --force.
lv24-seo properties --json	List configured providers, their target and whether a token is present.
lv24-seo stats --days 7 --lag-days 2 --json	Read-only per-provider KPIs for the current and previous window; no store writes.

Authentication 4

Command	Description	Copy
lv24-seo auth status --json	Show which providers have a token and where it comes from; values are never read back.
lv24-seo auth set --provider gsc --stdin	Store one provider secret from stdin in the OS keychain or the 0600 file fallback.
lv24-seo auth login --provider gsc	Print the manual token steps for GSC or Yandex; nothing is written.
lv24-seo auth logout --provider gsc	Remove a stored provider secret; environment-provided values stay read-only.

Configuration 1

Command	Description	Copy
lv24-seo config show --json	Print the effective config with secret-looking keys redacted.

Google Search Console 2

Command	Description	Copy
lv24-seo gsc query --start 2026-11-01 --end 2026-11-07 --dimensions query,page --limit 100	Query GSC search analytics for an explicit date range and dimensions.
lv24-seo sitemap submit --property sc-domain:example.com --url https://example.com/sitemap.xml	Plan a GSC sitemap submission; a dry run without --allow-write returns the confirm token.

Yandex Webmaster 3

Command	Description	Copy
lv24-seo yandex queries --limit 100 --json	Top Yandex queries for the configured host.
lv24-seo yandex indexing --json	Indexing history, search events, problems and counters for the host.
lv24-seo yandex recrawl --url https://example.com/page	Plan a Yandex recrawl queue; a dry run without --allow-write returns the confirm token.

IndexNow 1

Command	Description	Copy
lv24-seo indexnow submit --host example.com --key your-indexnow-key --url https://example.com/page	Plan an IndexNow submission; a dry run without --allow-write returns the confirm token.

Crawl and audit 1

Command	Description	Copy
lv24-seo crawl --start https://example.com --max-urls 500 --json	Crawl one site within the URL budget, run all rules and store pages and issues.

Reports 2

Command	Description	Copy
lv24-seo report weekly --days 7 --lag-days 2 --out reports/	Build the weekly digest, optionally write report.json/report.html and deliver it with --send.
lv24-seo report diff --markdown	Diff two stored weekly snapshots without provider calls; --markdown prints a PR-ready summary.

Scheduling 2

Command	Description	Copy
lv24-seo schedule install --kind weekly --print	Install the weekly or daily report job, or preview it with --print.
lv24-seo schedule print --cron "0 6 * * 1" --target systemd	Render a cron, systemd or Windows Task Scheduler artefact without touching the host.

Agents and MCP 4

Command	Description	Copy
lv24-seo mcp serve --transport stdio	Run the MCP server over stdio or streamable HTTP.
lv24-seo install --client claude --print	Merge the MCP server entry into a host client config; --print shows the JSON.
lv24-seo export tools --out schemas/tools.json	Write the MCP tool registry to schemas/tools.json.
lv24-seo export skills --out skills	Copy the packaged agent skills to --out.

Every command also accepts --help, which prints the authoritative flag list for the installed version.

Global conventions

Output envelope

With --json, a command prints exactly one JSON document and nothing else:

{ "ok": true, "data": {}, "meta": { "version": "0.5.2", "duration_ms": 812 }, "warnings": [] }

A failed command uses the same shape with ok: false and an error object instead of data:

{ "ok": false, "error": { "code": "AUTH_REQUIRED", "message": "Google Search Console token is missing", "retryable": false, "next_action": "lv24-seo auth login --provider gsc" }, "meta": { "version": "0.5.2" }, "warnings": ["gsc: token missing"] }

• data is command-specific. meta always carries version and often adds duration_ms, truncated, data_age_days, limitations, locale or complete.
• warnings are short human-readable strings. Aggregated commands such as stats stay ok: true when one provider fails; the failure is counted in coverage and reported in warnings.
• Without --json you get a compact plain-text summary on stdout, followed by any warnings and the error line. Neither mode emits ANSI colour codes.
• config show adds meta.redacted: true; secret-looking keys are masked with ***.

Exit codes

Code	Meaning	Error codes that map here
0	Success. The envelope is ok: true.	—
1	Unexpected internal failure.	INTERNAL
2	Usage or configuration problem.	INVALID_INPUT, CONFIG_INVALID, CONFIRM_REQUIRED, WRITE_DISABLED
3	Authentication problem.	AUTH_REQUIRED, AUTH_INVALID
4	Quota or upstream failure.	QUOTA_EXCEEDED, UPSTREAM_UNAVAILABLE
5	Partial result: truncated output.	TRUNCATED

WRITE_DISABLED exits 2, not 4: a write was refused before any provider call. Exit 5 is reserved for a successful envelope that is both truncated and marked meta.strict; no 0.5.2 flag sets strict mode, so scripts should treat 5 as a partial result rather than a hard failure. Branch on the exit code and error.code, never on the human-readable text.

Configuration and flags

• --config PATH selects a specific seo.toml. The path must exist; a missing file is CONFIG_INVALID, not a silent fallback. The resolved path is absolute and normalised, so scheduler artifacts and relative settings do not depend on the process working directory.
• Without --config, the engine looks for ./seo.toml, then the platform user config file (%APPDATA%\lv24-seo\config.toml on Windows, ~/.config/lv24-seo/config.toml on Linux).
• LV24_SEO_* environment variables override values from the file. .env files are not loaded automatically; export the variables in the shell or the service unit that runs the command.
• mcp serve is a long-running server and takes neither --json nor --config.

doctor --json reports meta.data_dir and meta.data_dir_source (config when the effective directory is absolute, working directory when it is relative) and adds a warning when a relative directory is ambiguous next to a config file. A relative directory does not fail the check.

The full key list, defaults and secret handling live in the configuration reference.

Read-only by default and the write gate

Only sitemap submit, yandex recrawl and indexnow submit can change provider state. They use a two-step flow:

1. Run the command without --confirm. It returns a dry run with data.plan, data.plan_hash, data.confirm_token and meta.dry_run: true.
2. Set a long random LV24_SEO_WRITE_SECRET in the same shell, then re-run with --allow-write --confirm TOKEN within five minutes.

The token is an HMAC over the action, target, full plan hash and expiry, so changing any input invalidates it. With an initialised workspace the CLI attaches the SQLite idempotency ledger, so a replayed token returns status: skipped with reason: duplicate and the provider is called once. Without a data directory the apply still runs, but the envelope warns that replay protection is off for the token's five-minute lifetime; a dry run opens no ledger and creates no database. IndexNow actually submits URLs. GSC sitemap submit and Yandex recrawl currently return WRITE_DISABLED instead of pretending the provider call happened.

Logging

Logging is opt-in. LV24_SEO_LOG_LEVEL=INFO (or DEBUG, WARNING, …) installs the redacting handler in the CLI and lv24-seo mcp serve; an unset variable leaves the caller's logging configuration untouched. Output is one JSON line per record when stderr is not a terminal and a plain line otherwise. The MCP transport logs to stderr only; stdout stays the protocol. The --json envelope remains the stable diagnostic interface.

Determinism and honesty

• Dates are ISO-8601 (2026-11-10); timestamps are ISO-8601 UTC (2026-11-14T12:00:00+00:00).
• CLI field order is stable, stored snapshot payloads are key-sorted, and visible output contains no random identifiers. Reports and diffs are meant to be diffed between runs.
• Bounded responses carry truncated, total, data_age_days and limitations[] where they apply. A metric present in only one window is reported as unknown, never as zero.
• --days accepts 1..3660; a larger value fails with INVALID_INPUT and exit 2.
• No command prints a token, cookie or full Authorization header.

Command groups

Group	Commands	What it touches
Start	version, doctor, init, properties, stats	Local files and the environment; stats reads provider KPIs without writing.
Authentication	auth status, auth set, auth login, auth logout	The local secret store; login only prints instructions.
Configuration	config show	The effective config, with credentials redacted.
Google Search Console	gsc query, sitemap submit	Read-only queries; sitemap submit is a gated write.
Yandex Webmaster	yandex queries, yandex indexing, yandex recrawl	Read-only queries; recrawl is a gated write.
IndexNow	indexnow submit	A gated write that actually submits URLs.
Crawl and audit	crawl	Provider-independent; stores local pages and issues when a store is configured.
Reports	report weekly, report diff	weekly stores a local snapshot; diff is read-only.
Scheduling	schedule print, schedule install	print renders only; install writes host scheduler files.
Agents and MCP	mcp serve, install, export tools, export skills	Host config, generated files or a local server.

Examples

Dashboard snapshot

lv24-seo stats --days 7 --lag-days 2 --json

Read-only and store-free. Services always appear in the order gsc, yandex_webmaster, yandex_metrika, bing, crux, psi; metrics contains only reported values, with no zero fill and no cross-engine totals. A provider failure is isolated and increments coverage.failed.

Search Console

lv24-seo gsc query --start 2026-11-01 --end 2026-11-07 --dimensions query,page --limit 100 --json

--start and --end are required. There is no --days shorthand and no --property override: the property comes from [providers.gsc] in seo.toml. Dimensions are comma-separated and limited to query, page, country, device and date.

Yandex

lv24-seo yandex queries --limit 100 --json
lv24-seo yandex indexing --json

yandex queries returns top rows, not a full query-by-page join: Yandex exposes at most 3,000 queries per period. yandex indexing reports indexing history, in-search counts, diagnostics and search-URL events for the configured host_id.

Crawl

lv24-seo crawl --start https://example.com --max-urls 500 --json

The crawler respects robots.txt, follows same-host links breadth-first, runs every rule and stores pages and issues when a store is configured. data.sitemap_coverage compares the sitemap with what the crawl saw in six buckets. When it returns complete: false, the affected buckets are candidates, not confirmed findings; limitations[] names the truncated input.

Reports

lv24-seo report weekly --days 7 --lag-days 2 --out reports/ --json
lv24-seo report diff --markdown

report weekly builds and stores a snapshot; add --send to deliver through the channels enabled in seo.toml. --out writes canonical English report.json and a locale-rendered report.html. report diff compares two stored weekly snapshots, never calls a provider, and needs two runs for different periods. --markdown prints only Markdown on stdout; warnings go to stderr.

Scheduling

lv24-seo schedule print --cron "0 6 * * 1" --target systemd --json
lv24-seo schedule install --kind weekly --print

print renders the artefact without touching the host. install writes the cron block, systemd user units or Task Scheduler XML, and the generated job runs report weekly --send --json. Only simple cron expressions (M H * * * and M H * * DOW) convert to systemd or Windows schedules.

MCP and agent clients

lv24-seo install --client cursor --print
lv24-seo mcp serve --transport http --port 8765

install merges the lv24-seo server entry into the host config instead of replacing the file; --print shows the exact JSON. mcp serve defaults to stdio and accepts streamable HTTP with --transport http.

Authentication

lv24-seo auth status --json
lv24-seo auth set --provider gsc --stdin

auth set reads the secret from stdin or a hidden prompt and stores it in the OS keychain, or in the opt-in 0600 file fallback. It prints only {provider, stored, source}. auth status reports presence and source (env, keyring, file, missing), never a value.

Export

lv24-seo export tools --out schemas/tools.json
lv24-seo export skills --out skills/

export tools writes the generated MCP registry for non-MCP agents; export skills copies the packaged SKILL.md files and their manifest. Both write local files only.

Related

• Configuration reference
• Data sources and quotas
• MCP and agent skills
• Troubleshooting

Source: _source/engine-cli.md, _source/engine-mcp.md, _source/engine-releases-0.5.2.md; 0.5.2 --help output in the engine repository.