DOCS SMARTSPEC / CLI

CLI Reference

5 commands: audit, page, doctor, help, version. That's it.

Syntax

smartspec <command> [args] [flags]

Run smartspec help for inline help.

audit

Run a technical SEO audit against a URL.

smartspec audit <url> [flags]
smartspec audit https://example.com -f json -m 1 --no-fixes

Flags

-f, --format <t>

Output format. Values: console (default), json, html, markdown, text, xml, llm. Format details →

-o, --output <path>

Write output to a file instead of stdout. Works with every format.

-m, --max-pages <n>

Crawl limit (default: 250). Use -m 1 for a single-page audit.

--only <modules>

Restricts the audit to the listed modules (CSV). Example: --only schema, --only schema,performance. Valid modules: page, schema, images, links, a11y, hreflang, social, robots, sitemap, ai-readiness, redirects, security, performance, mobile, content-quality, analytics. More ergonomic than --categories for surgical audits.

--categories <list>

Filter findings to a subset of categories. Example: --categories page,schema,a11y. Kept for backwards compatibility; prefer --only.

--no-fixes

Drops the suggested_fix field from findings. Smaller output.

--no-plugins

Skip optional Python plugins.

-q, --quiet

Suppress progress messages on stderr.

--verbose

Verbose logs on stderr.

Examples

Single-page audit, pretty JSON:

smartspec audit https://example.com -f json -m 1

HTML report saved to file:

smartspec audit https://example.com -f html -o report.html

Extract the score in a CI pipeline:

smartspec audit $URL -f json -q | jq '.score'

Surgical audit, JSON-LD only:

smartspec audit https://example.com --only schema -f markdown -o schema.md

page

Deep audit of a single URL: every applicable module on one page, no crawl.

smartspec page <url> [flags]
smartspec page https://example.com/landing -f markdown

Accepts the same flags as audit except -m (irrelevant).

doctor

Sanity-checks the environment: network, Python (for plugins), installed version.

smartspec doctor

Exits 0 if all OK. Run it in CI before an audit to fail-fast on incomplete environments.

help

Inline help: shows the 5 commands, the 16 --only modules, the 7 formats, the env vars.

smartspec help

version

Prints version and commit hash.

smartspec version
# smartspec 0.3.0 (c038679)

Exit codes

Code	Meaning
0	Audit completed (even with findings).
1	Generic error (invalid URL, network, failed fetch, parse error).
130	Interrupted via `Ctrl-C` (SIGINT).

Note: SmartSpec doesn't exit non-zero based on score. Use jq for fail-on-threshold in CI: smartspec audit $URL -f json | jq -e '.score >= 80'.

Environment variables

GOOGLE_PSI_API_KEY

PageSpeed Insights v5 API key. Without one PSI has a very low free quota.

SMARTSPEC_VERSION

Override for the version shown by smartspec version (build-time).

Continue

Install

How to install SmartSpec.

Output formats

The 7 output formats in detail.

Integrations

Claude Code, Cursor, jq.