DOCS SMARTSPEC / CLI

CLI Reference

5 comandi: audit, page, doctor, help, version. Tutto qui.

Sintassi

smartspec <comando> [argomenti] [flag]

Lancia smartspec help per l'help inline.

audit

Lancia un audit SEO tecnico su un URL.

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

Flag disponibili

-f, --format <t>

Formato di output. Valori: console (default), json, html, markdown, text, xml, llm. Dettagli formati →

-o, --output <path>

Scrive l'output su file invece di stdout. Funziona con tutti i formati.

-m, --max-pages <n>

Limite di pagine da crawlare (default: 250). Usa -m 1 per audit single-page.

--only <moduli>

Limita l'audit ai moduli elencati (CSV). Es: --only schema, --only schema,performance. Moduli validi: page, schema, images, links, a11y, hreflang, social, robots, sitemap, ai-readiness, redirects, security, performance, mobile, content-quality, analytics. Più ergonomico di --categories per audit chirurgici.

--categories <list>

Filtra i findings su un sottoinsieme di categorie. Es: --categories page,schema,a11y. Mantenuto per retro-compatibilità; preferisci --only.

--no-fixes

Esclude il campo suggested_fix dai findings. Riduce la dimensione dell'output.

--no-plugins

Salta i plugin Python opzionali.

-q, --quiet

Sopprime i messaggi di progresso su stderr.

--verbose

Log verbosi su stderr.

Esempi

Single-page audit, JSON pretty-print:

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

Report HTML salvato su file:

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

Estrai lo score in pipeline CI:

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

Audit chirurgico, solo JSON-LD:

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

page

Deep audit di una singola URL: tutti i moduli applicabili ma su una sola pagina, senza crawl.

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

Accetta gli stessi flag di audit tranne -m (irrilevante).

doctor

Sanity check dell'environment: rete, Python (per plugin), versione installata.

smartspec doctor

Esce con 0 se tutto OK. Usalo in CI prima di un audit per fail-fast su ambienti incompleti.

help

Help inline: mostra i 5 comandi, i 16 moduli --only, i 7 formati, le variabili d'ambiente.

smartspec help

version

Stampa versione e commit hash.

smartspec version
# smartspec 0.3.0 (c038679)

Exit code

Code	Significato
0	Audit completato (anche con findings).
1	Errore generico (URL invalido, rete, fetch fallito, parse error).
130	Interrotto via `Ctrl-C` (SIGINT).

Nota: SmartSpec non esce con codice diverso da 0 in base allo score. Usa jq per fail-on-threshold in CI: smartspec audit $URL -f json | jq -e '.score >= 80'.

Variabili d'ambiente

GOOGLE_PSI_API_KEY

API key di PageSpeed Insights v5. Senza chiave PSI ha una quota free molto bassa.

SMARTSPEC_VERSION

Override per la versione mostrata da smartspec version (build-time).

Continua

Installazione

Come installare SmartSpec.

Output formats

I 7 formati di output in dettaglio.

Integrazioni

Claude Code, Cursor, jq.