Olostep CLI - Olostep Docs

Pacchetto NPM: olostep-cli Repository: github.com/olostep-api/olostep-cli CLI per l’Olostep API — scrape, search, map, crawl, answer, e batch il web dal tuo terminale. Ogni comando restituisce JSON così da poter essere facilmente integrato in jq, agenti e CI. JavaScript puro, Node 18+, nessun binario nativo da scaricare. Si installa in meno di un secondo, avvia in ~200 ms, distribuito come un singolo pacchetto di ~100 KB.

Installazione

Requisiti: Node.js 18+.

npm (consigliato)
One-liner (macOS / Linux)
One-liner (Windows)
No-install (npx)

npm install -g olostep-cli
olostep init

curl -fsSL https://olostep.com/install.sh | sh
olostep init

Lo script verifica Node 18+, esegue npm install -g olostep-cli, e ricorre a sudo se necessario.

iwr -useb https://olostep.com/install.ps1 | iex
olostep init

Stesso concetto dello script per macOS/Linux, ma per PowerShell.

npx -y olostep-cli@latest --help

Ottimo per provare un singolo comando senza un’installazione globale.

olostep init è il passo successivo consigliato — ti autentica, installa le competenze Olostep nei tuoi agenti AI, e configura il server MCP, tutto in un unico comando. Gli script one-liner avvolgono npm install -g olostep-cli con un controllo Node 18+ e un fallback sudo, quindi funzionano anche se non sei sicuro della tua configurazione locale. Piattaforme: macOS (Apple Silicon e Intel), Linux (x64 e arm64), Windows (x64 e arm64).

Configurazione

Un comando fa tutto — autenticazione, installazione delle competenze, e installazione del server MCP:

olostep init

Flag: --skills-only, --mcp-only, --no-browser, --relogin. Per solo autenticarsi (senza competenze/MCP):

olostep login
olostep login --no-browser     # stampa l'URL (utile su SSH)

Il browser si apre alla pagina di autenticazione Olostep; clicchi su Authorize, e la CLI salva la tua chiave localmente. Alternativa — imposta una variabile d’ambiente. Utile per CI:

export OLOSTEP_API_KEY=your_key_here

Ottieni una chiave dalla dashboard delle chiavi API. Dove viene memorizzata la chiave (dopo olostep login):

OS	Percorso
macOS	`~/Library/Application Support/olostep-cli/credentials.json`
Linux	`~/.config/olostep-cli/credentials.json`
Windows	`%USERPROFILE%\AppData\Roaming\olostep-cli\credentials.json`

Disconnessione

olostep logout            # chiede conferma, poi rimuove credentials.json
olostep logout --dry-run  # solo anteprima — vedi cosa succederebbe
olostep logout --yes      # salta la conferma (per script)
olostep logout --json     # output leggibile dalla macchina

logout ti avvisa anche se le variabili d’ambiente OLOSTEP_API_KEY / OLOSTEP_API_TOKEN o un file .env nella tua directory corrente contengono ancora una chiave — queste hanno priorità sul file delle credenziali, quindi eliminare solo il file potrebbe non essere sufficiente. L’output include i comandi esatti per annullare l’impostazione su PowerShell e bash/zsh.

Inizio rapido

olostep login

olostep search "best web scraping APIs 2025" --limit 5
olostep answer "What does Olostep do?"
olostep map "https://example.com" --top-n 20
olostep scrape "https://example.com" --formats markdown
olostep crawl "https://docs.example.com" --max-pages 50
olostep batch-scrape urls.csv --formats markdown,html

Ogni comando stampa il suo risultato JSON su stdout per impostazione predefinita. Passa --out <path> per salvare su un file.

Cosa può fare?

Vuoi…	Comando	Prodotto Olostep
Cercare sul web	`search`	Searches
Ottenere una risposta ricercata	`answer`	Answers
Scoprire URL su un sito	`map`	Maps
Estrarre una pagina	`scrape`	Scrapes
Estrarre ogni pagina su un sito	`crawl`	Crawls
Estrarre molti URL da un CSV	`batch-scrape`	Batches
Estrarre campi strutturati	`--parser-id` su `batch-scrape`	Parsers
Rieseguire un risultato per ID	`scrape-get`	Scrapes
Taggare/organizzare un batch	`batch-update`	Batches

Output

Ogni comando stampa il suo risultato JSON su stdout per impostazione predefinita.

Flag	Comportamento
(nessuno)	Stampa JSON su stdout (UTF-8, indentato)
`--out <path>`	Scrivi JSON su quel file invece
`--out -`	Esplicitamente stdout (come predefinito)

Le linee di progresso e log vanno su stderr, quindi stdout rimane pulito per le pipe.

olostep map "https://example.com" --top-n 20 | jq '.urls[:10]'
olostep scrape "https://example.com" | jq .result.markdown_content
olostep search "topic" --json | jq '.links[].url'

Scegliere tra loro:

search — vuoi un elenco di URL e frammenti rilevanti per una query. La CLI cerca sul web per te.
answer — vuoi una risposta sintetizzata, non il contenuto grezzo della pagina. La CLI fa la ricerca per te.
scrape — hai già l’URL e vuoi estrarre contenuto pulito.
crawl — vuoi ogni pagina su un sito (o un sottoinsieme filtrato) senza enumerare manualmente gli URL.
batch-scrape — hai un elenco di URL e vuoi processarli in parallelo.

Comandi

Usa olostep <command> --help per ogni opzione.

`search`: ricerca web live

Restituisce link organici deduplicati (URL, titolo, descrizione).

Opzione	Descrizione
`--limit`	Numero di risultati, predefinito 12, massimo 25
`--include-domains`	Domini separati da virgola per restringere i risultati
`--exclude-domains`	Domini separati da virgola da escludere
`--out`	File o `-`
`--json`	Output leggibile dalla macchina

olostep search "TypeScript CLI tools" --limit 10
olostep search "open source projects" --include-domains "github.com" --limit 5
olostep search "AI agents" --json | jq '.links[].url'

`answer`: risposta ricercata

Sincrono — restituisce quando la risposta è pronta.

Opzione	Descrizione
`--out`	File o `-`
`--json-format`	Forma JSON opzionale per output strutturato

olostep answer "What does this company build?" --out answer.json
olostep answer "Extract facts" --json-format '{"company":"","year":""}' --out -

`map`: scoprire URL

Opzione	Descrizione
`--out`	Percorso file o `-`
`--top-n`	Max URL da restituire
`--search-query`	Query opzionale per guidare la scoperta
`--include-subdomain` / `--no-include-subdomain`	Sottodomini
`--include-url` / `--exclude-url`	Pattern URL ripetibili
`--cursor`	Cursore di paginazione

olostep map "https://example.com" --top-n 100 --search-query "blog"

`scrape`: un URL

Formati: html, markdown, text, json, raw_pdf, screenshot (separati da virgola; predefinito markdown).

Opzione	Descrizione
`--formats`	Separati da virgola
`--country`	Codice paese (es. `US`, `GB`)
`--wait-before-scraping`	Attendi prima di estrarre (ms)
`--payload-json` / `--payload-file`	Opzioni avanzate come JSON (es. `"max_age": 86400` per optare nel caching — vedi Caching)

olostep scrape "https://example.com" --formats markdown,html
olostep scrape "https://example.com" --payload-file options.json --out -

`scrape-get`: recupera per ID

olostep scrape-get "scrape_abc123" --out -

`crawl`: intero sito

Inizia un crawl, interroga fino al completamento, poi recupera i contenuti delle pagine. Formati di recupero: markdown, html, json. Flag notevoli: --max-pages, --max-depth, --include-subdomain, --include-external, --include-url, --exclude-url, --search-query, --top-n, --webhook, --crawl-timeout, --formats, --pages-limit, --pages-search-query, --poll-seconds, --poll-timeout, --dry-run.

olostep crawl "https://docs.example.com" --max-pages 50 --formats markdown,html
olostep crawl "https://example.com" --max-pages 10 --dry-run

`batch-scrape`: CSV

Il CSV deve avere una riga di intestazione con colonne custom_id (o id) e url.

custom_id,url
example,https://example.com
iana,https://iana.org
docs,https://docs.olostep.com

Opzione	Descrizione
`--formats`	`markdown`, `html`, `json` (separati da virgola)
`--country`	Codice paese opzionale
`--parser-id`	ID parser per estrazione strutturata
`--poll-seconds`, `--log-every`, `--items-limit`	Polling e paginazione
`--dry-run`	Stampa il payload ed esci

olostep batch-scrape urls.csv --formats markdown,html
olostep batch-scrape urls.csv --parser-id "<PARSER_ID>" --out results.json

Sincrono — interroga fino al completamento del batch, poi recupera ogni elemento.

`batch-update`: metadati batch

Richiede uno di --metadata-json o --metadata-file (oggetto JSON).

olostep batch-update "batch_abc123" --metadata-json '{"team":"growth"}'
olostep batch-update "batch_abc123" --metadata-file meta.json

Comandi di autenticazione

olostep login                      # accesso PKCE tramite browser
olostep logout                     # rimuovi credenziali salvate
olostep status                     # mostra stato auth, percorsi config, versione

olostep auth login                 # uguale a olostep login
olostep auth logout                # uguale a olostep logout
olostep auth status                # uguale a olostep status
olostep auth set-key <key>         # salva direttamente una chiave API (senza browser)

auth set-key è utile per CI e script — scrivi direttamente la chiave senza passare per il flusso del browser.

Installa il server MCP

La CLI scrive il server Olostep MCP nella configurazione del tuo agente — nessuna modifica JSON necessaria.

olostep mcp install                          # rileva agenti, endpoint ospitato
olostep mcp install --agent cursor           # solo Cursor
olostep mcp install --transport stdio        # npx locale invece di ospitato
olostep mcp install --no-global              # scrivi nel progetto corrente
olostep mcp install --dry-run --json         # solo piano
olostep mcp uninstall                        # rimuovi l'entry olostep
olostep list mcp                             # mostra quali agenti lo hanno

Opzione	Descrizione
`--agent`	Agente specifico, ripetibile. Supportati: `cursor`, `claude`, `claude-desktop`, `windsurf`, `vscode`, `kilo`, `opencode`, `continue`, `codex`
`--all-agents` / `--no-all-agents`	Target ogni agente rilevato (predefinito)
`--transport`	`http` (ospitato, consigliato) o `stdio` (locale `npx olostep-mcp`)
`--global` / `--no-global`	Config per utente (predefinito) vs locale progetto
`--api-key`	Chiave da incorporare; predefinito alle credenziali risolte
`--dry-run`	Mostra il piano senza scrivere
`--json`	Output leggibile dalla macchina

L’endpoint ospitato a https://mcp.olostep.com/mcp utilizza Authorization: Bearer <key> — nessun processo Node locale richiesto. La CLI unisce solo la chiave olostep nella tua configurazione esistente. Riavvia il tuo agente dopo l’installazione.

Competenze per agenti AI

La CLI distribuisce 13 competenze Olostep — file SKILL.md installati in Claude Code, Cursor, e altri agenti così che sappiano cosa può fare Olostep e quando usarlo.

olostep add skills                     # installa tutto in ogni agente rilevato
olostep skills install                 # stesso (alias)
olostep skills update                  # reinstalla / aggiorna tutte le competenze
olostep skills list                    # vedi cosa è installato e dove
olostep skills uninstall               # rimuovi tutte le competenze

Filtra cosa viene installato:

olostep add skills --category usage    # solo competenze core web-data
olostep add skills --skill scrape --skill map
olostep add skills --agent cursor --agent claude

Vedi Competenze per l’elenco completo e le opzioni.

Controlli di salute

olostep doctor                         # esegui tutti i controlli
olostep doctor --skip-network          # solo auth + config, nessuna chiamata HTTP
olostep doctor --json                  # NDJSON — un record per controllo (buono per CI)
olostep doctor --fail-on-warn          # esci 1 anche su avvisi

Controlli: chiave API presente, chiave API raggiungibile, endpoint MCP raggiungibile, file di configurazione esistente per ogni agente rilevato. Uso in CI:

olostep doctor --json --skip-network | jq 'select(.status == "fail")'

Versione e aggiornamenti

olostep version                        # versione CLI, versione Node, canale
olostep version --json                 # leggibile dalla macchina: { cli, node, channel }
olostep update                         # aggiorna all'ultima versione (npm install -g olostep-cli@latest)
olostep update --check                 # controlla se è disponibile una versione più recente, non installa

Variabili d’ambiente

Variabile	Effetto
`OLOSTEP_API_KEY`	Chiave API
`OLOSTEP_API_TOKEN`	Chiave API (alias legacy)
`OLOSTEP_JSON=1`	Forza l’output JSON su ogni comando (come `--json` globalmente)
`OLOSTEP_NO_UPDATE_CHECK=1`	Silenzia l’avviso “aggiornamento disponibile”
`OLOSTEP_CLI_CONFIG_DIR`	Sovrascrive la directory delle credenziali

Note per Windows / PowerShell

PowerShell tokenizza , e * diversamente da bash — cita gli argomenti:

olostep scrape "https://example.com" --formats "markdown,html"
olostep map   "https://example.com" --include-url "/*"
olostep answer "Extract facts" --json-format '{"company":"","year":""}'

Le virgolette singole sono più sicure per i valori JSON (nessuna interpolazione $).

Vedi cosa è installato

olostep list skills    # competenze Olostep installate e quali agenti le hanno
olostep list mcp       # quali agenti hanno il server Olostep MCP, e il trasporto

Flag globali

Flag	Descrizione
`-V`, `--version`	Versione
`-h`, `--help`	Aiuto

--out, --timeout, e --api-key sono disponibili su ogni comando di dati.

Sicurezza

Tieni le chiavi API fuori dal controllo del codice sorgente; ruota se trapelate. olostep logout rimuove il file delle credenziali locali e ti dice se qualche sorgente env-var contiene ancora una chiave.

Correlati

Maps · Crawls · Batches · Answers · Searches · Skills · MCP Server

​Installazione

​Configurazione

​Disconnessione

​Inizio rapido

​Cosa può fare?

​Output

​Comandi

​search: ricerca web live

​answer: risposta ricercata

​map: scoprire URL

​scrape: un URL

​scrape-get: recupera per ID

​crawl: intero sito

​batch-scrape: CSV

​batch-update: metadati batch

​Comandi di autenticazione

​Installa il server MCP

​Competenze per agenti AI

​Controlli di salute

​Versione e aggiornamenti

​Variabili d’ambiente

​Note per Windows / PowerShell

​Vedi cosa è installato

​Flag globali

​Sicurezza

​Correlati