Guida completa a Osiris — CLI, configurazione e MCP

01 · Installazione e primo audit

Inizia in pochi passaggi.

I binari self-contained non richiedono l'installazione di .NET. Scarica l'archivio per la tua piattaforma dalla release stabile.

Sistema	Archivio
macOS Apple Silicon	`osiris-osx-arm64.tar.gz`
macOS Intel	`osiris-osx-x64.tar.gz`
Linux x64	`osiris-linux-x64.tar.gz`
Windows x64	`osiris-win-x64.zip`

macOS / Linux · esempio Apple Silicon

tar -xzf osiris-osx-arm64.tar.gz
sudo install -m 0755 osiris /usr/local/bin/osiris
osiris --version

Windows PowerShell

# Estrai lo ZIP e aggiungi la cartella al PATH
osiris.exe --version
osiris.exe analyze start https://example.com

Le release includono SHA256SUMS. Su macOS/Linux verifica con shasum -a 256 -c SHA256SUMS --ignore-missing (su Linux è disponibile anche sha256sum --ignore-missing -c SHA256SUMS). Su Windows confronta (Get-FileHash .\osiris-win-x64.zip -Algorithm SHA256).Hash con il valore nel file. Se Gatekeeper blocca il binario macOS scaricato, la guida di installazione nel README spiega come rimuovere l'attributo di quarantena.

Primo audit

Senza configurazione aggiuntiva, Osiris esegue il crawl e salva i dati localmente in ~/.osiris.

osiris analyze start https://example.com --depth 2 --max-pages 50 --wait
osiris report get --format md
osiris issues list --quick-wins
osiris geo check --url https://example.com

Ogni comando accetta -h per l'help e --json per l'output strutturato. osiris --version mostra la versione installata. Puoi spostare l'intera cartella dati impostando OSIRIS_HOME.

02 · Riferimento CLI

Audit, report e problemi.

Comando	Descrizione
`osiris analyze start <url>`	Avvia un audit; per impostazione predefinita attende il completamento.
`osiris analyze status`	Mostra stato, avanzamento e contatori di un audit.
`osiris analyze cancel`	Richiede l'annullamento di un audit in corso.
`osiris analyze list`	Elenca gli audit recenti (default 20, massimo 200 con `--limit`).
`osiris report get`	Legge un report in Markdown o JSON; `--output` lo scrive su file.
`osiris issues list`	Filtra i rilievi per gravità, categoria, URL, controllo, priorità o fascia.
`osiris context`	Mostra percorsi, audit corrente, valori predefiniti e integrazioni.
`osiris context set --audit-id <id>`	Imposta l'audit corrente per i comandi successivi.
`osiris config list\|get\|set`	Legge e aggiorna le impostazioni locali; i segreti sono mascherati.

Opzioni di `analyze start`

Opzione	Descrizione
`--depth <n>`	Profondità massima del crawl, da 0 a 10 (default 2).
`--max-pages <n>`	Numero massimo di pagine da scansionare (default 50).
`--max-concurrency <n>`	Numero massimo di richieste parallele.
`--include-subdomains`	Include i sottodomini nel crawl.
`--respect-robots-txt` / `--no-respect-robots-txt`	Abilita o disabilita il rispetto delle regole robots.txt.
`--user-agent <ua>`	Imposta lo User-Agent del crawler.
`--analyze-content` / `--no-analyze-content`	Attiva o disattiva i controlli su contenuti sottili, leggibilità, heading e duplicati.
`--probe-resources` / `--no-probe-resources`	Attiva o disattiva la misurazione di CSS, JS e immagini (peso, richieste, compressione e cache).
`--max-resource-probes <n>`	Numero massimo di risorse misurate, da 0 a 200; 0 disattiva il controllo.
`--min-words <n>`	Soglia per rilevare pagine con contenuto sottile, da 50 a 5000 parole (default 300).
`--use-page-speed-insights` / `--no-use-page-speed-insights`	Include i Core Web Vitals tramite PageSpeed Insights.
`--use-gsc` / `--no-use-gsc`	Include dati di Google Search Console.
`--use-keywords` / `--no-use-keywords`	Include opportunità e dati keyword.
`--wait` / `--no-wait`	Attende il completamento (default) oppure restituisce subito l'ID dell'audit.
`--timeout <min>`	Attesa massima con `--wait` (default 40 minuti).
`--fail-on <livello>`	Esce con codice 3 se trova rilievi almeno al livello indicato: `none`, `low`, `medium`, `high` o `critical`.

Report e filtri issue

Comando / opzione	Descrizione
`report get --format <md\|json>`	Seleziona il formato del report (default Markdown).
`report get --output <percorso>`	Scrive il report su file e stampa il percorso; `--overwrite` consente di sovrascriverlo.
`report get --compact`	Riduce i campi verbosi nel report JSON.
`--severity <livello>`	Filtra per `info`, `low`, `medium`, `high` o `critical`.
`--category <cat>`	Filtra per `technical`, `onpage`, `content`, `performance`, `accessibility`, `security`, `geo` o `other`.
`--url <testo>` / `--check <id>`	Limita ai rilievi il cui URL contiene il testo o a un controllo specifico.
`--min-priority <n>` / `--band <P0\|P1\|P2\|P3>`	Filtra per punteggio minimo o fascia di priorità.
`--quick-wins`	Mostra solo i rilievi ad alto impatto e basso sforzo.
`--sort <criterio>`	Ordina per `priority` (default), `severity`, `impact` o `quick-wins`.
`--limit <n>` / `--compact`	Limita i risultati (default 100, massimo 1000) e riduce le descrizioni.
`--fail-on <livello>`	Esce con codice 3 se esistono rilievi pari o superiori alla gravità indicata.

03 · Analisi aggiuntive

GEO, Search Console e keyword.

Le integrazioni sono opzionali: senza credenziali, crawl e audit principali continuano a funzionare.

Comando	Uso e opzioni principali
`osiris geo check`	Valuta crawler AI in robots.txt, llms.txt, citabilità, E-E-A-T e dati strutturati. Usa `--audit-id` oppure `--url <url>` (senza audit, fino a 25 pagine; `--max-pages` accetta 1–50). `--compact` riduce l'output.
`osiris geo generate --output <cartella>`	Genera llms.txt, indicazioni per robots.txt e JSON-LD. Accetta `--policy allow\|block-training` e `--overwrite`.
`osiris gsc auth --interactive`	Avvia l'autorizzazione OAuth nel browser; verifica credenziali e proprietà accessibili.
`osiris gsc queries`	Query principali; supporta `--site-url`, `--audit-id`, `--days` (1–480, default 28) e `--limit`.
`osiris gsc pages`	Pagine di atterraggio principali; accetta le stesse opzioni di query.
`osiris gsc inspect --url <url>`	Controlla lo stato di indicizzazione di un URL; accetta anche `--site-url` e `--audit-id`.
`osiris keywords ideas`	Espande seed o topic dell'audit in idee keyword; opzioni `--seeds`, `--limit`, `--location` e `--language`.
`osiris keywords gap --competitor <dominio>`	Trova keyword competitor non coperte dal sito; fino a 5 competitor. Richiede DataForSEO.

Per Search Console, --site-url accetta una proprietà URL, ad esempio https://example.com/, oppure una proprietà dominio come sc-domain:example.com. Le idee keyword senza DataForSEO possono usare autocomplete, ma non includono metriche di volume.

04 · Impostazioni e credenziali

Configura solo ciò che ti serve.

Imposta i valori con osiris config set --key <chiave> --value <valore>. Un valore vuoto azzera la chiave; config list maschera i segreti.

Chiave	Default	Descrizione
`userAgent`	`OsirisBot/1.0`	User-Agent del crawler.
`requestTimeoutSeconds`	`20`	Timeout per richiesta.
`defaultMaxPages`	`50`	Numero massimo di pagine per audit.
`defaultMaxDepth`	`2`	Profondità massima del crawl.
`defaultMaxConcurrency`	`4`	Richieste parallele.
`respectRobotsTxt`	`true`	Rispetta robots.txt.
`maxRequestsPerSecond`	`10`	Limite di frequenza delle richieste.
`maxRetries`	`2`	Tentativi per richiesta.
`allowPrivateNetworks`	`false`	Consente indirizzi privati/locali; configurabile solo da CLI o file.
`analyzeContent`	`true`	Abilita l'analisi dei contenuti.
`probeResources`	`true`	Misura le risorse delle pagine.
`maxResourceProbes`	`30`	Risorse misurate per audit.
`minWordCount`	`300`	Soglia per identificare contenuti sottili.
`usePageSpeedInsights`	`false`	Richiede Core Web Vitals tramite PageSpeed Insights.
`pageSpeedApiKey`	—	Chiave segreta PageSpeed; senza chiave si applica la quota pubblica.
`useGoogleSearchConsole`	`false`	Allega dati Search Console agli audit.
`gscSiteUrl`	—	Proprietà Search Console predefinita.
`gscDateRangeDays`	`28`	Intervallo predefinito dei dati GSC.
`gscMaxRows`	`100`	Massimo righe GSC.
`gscServiceAccountPath`	—	Percorso al JSON del service account Google.
`gscOAuthClientSecret`	—	Percorso al file client secret OAuth.
`geoAiPolicy`	`allow`	Policy crawler AI: `allow` o `block-training`.
`useKeywords`	`false`	Allega opportunità keyword agli audit.
`keywordMaxIdeas`	`50`	Numero massimo di idee keyword.
`keywordCompetitors`	—	Competitor predefiniti per il gap.
`keywordLocation`	`Italy`	Mercato per i dati keyword.
`keywordLanguage`	`it`	Lingua per i dati keyword.
`dataForSeoLogin` / `dataForSeoPassword`	—	Credenziali segrete DataForSEO.

Esempi

osiris config set --key defaultMaxPages --value 100
osiris config set --key usePageSpeedInsights --value true
osiris config set --key gscServiceAccountPath \
  --value ~/.osiris/gsc-service-account.json
osiris gsc auth

Variabili d'ambiente

OSIRIS_HOME
OSIRIS_PAGESPEED_API_KEY
OSIRIS_GEO_AI_POLICY

Altre chiavi di configurazione supportate sono documentate nel README del progetto.

05 · Agenti AI

Usa Osiris via MCP.

Il server MCP usa stdio e condivide gli stessi handler e risultati della CLI. Il processo gira localmente nel client: non occorre esporre un endpoint pubblico.

Claude Code

claude mcp add osiris -- osiris mcp serve

Configurazione di un client MCP

{
  "mcpServers": {
    "osiris": {
      "command": "osiris",
      "args": ["mcp", "serve"]
    }
  }
}

Strumenti esposti

Il server espone gli strumenti seguenti. I nomi MCP usano il prefisso osiris_ e corrispondono ai rispettivi comandi CLI.

Strumento MCP	Funzione
Contesto e configurazione
`osiris_context`	Mostra percorsi, audit corrente, impostazioni predefinite e integrazioni. È il punto di partenza consigliato per una sessione.
`osiris_context_set`	Imposta l'audit corrente da usare nei comandi successivi.
`osiris_config_get`	Legge il valore effettivo di una chiave di configurazione.
`osiris_config_list`	Elenca le chiavi di configurazione; i valori segreti restano mascherati.
`osiris_config_set`	Imposta o azzera una chiave di configurazione.
Audit
`osiris_analyze_start`	Avvia un audit SEO/GEO per un URL con i limiti e le opzioni scelti.
`osiris_analyze_status`	Restituisce stato, avanzamento e contatori dell'audit.
`osiris_analyze_cancel`	Richiede l'annullamento di un audit in corso.
`osiris_analyze_list`	Elenca gli audit recenti.
Report e rilievi
`osiris_report_get`	Recupera il report dell'audit in Markdown o JSON.
`osiris_issues_list`	Elenca e filtra i problemi per severità, categoria, priorità e quick win.
Visibilità GEO
`osiris_geo_check`	Analizza la visibilità nei motori AI e i segnali GEO di un sito o audit.
`osiris_geo_generate`	Genera llms.txt, indicazioni per robots.txt e JSON-LD consigliati.
Google Search Console
`osiris_gsc_auth`	Verifica l'autenticazione e le proprietà Search Console accessibili.
`osiris_gsc_queries`	Recupera le query di ricerca principali della proprietà.
`osiris_gsc_pages`	Recupera le pagine di atterraggio principali.
`osiris_gsc_inspect`	Controlla lo stato di indicizzazione di un URL.
Ricerca keyword
`osiris_keywords_ideas`	Genera idee keyword dai seed o dai temi individuati nell'audit.
`osiris_keywords_gap`	Individua keyword dei competitor non coperte dal sito; richiede DataForSEO.

Per gli strumenti Search Console e keyword, i risultati dipendono dalle integrazioni e dalle credenziali configurate. Tutti gli strumenti condividono i controlli e i dati locali della CLI.

06 · Privacy e sicurezza

Dati locali, crawl controllato.

Audit e configurazione sono conservati sotto ~/.osiris (oppure nella cartella indicata da OSIRIS_HOME). Le integrazioni esterne vengono usate solo se configurate. Gli indirizzi privati e locali sono bloccati per impostazione predefinita; il crawler applica limiti di profondità, pagine e concorrenza e rispetta robots.txt. I valori segreti non vengono stampati in chiaro dai comandi di configurazione.

README, sorgenti e release su GitHub