> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olostep.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Olostep CLI

> Interfaccia a riga di comando per scrape, search, map, crawl, answers e batches — output JSON per script, CI e agenti AI

**Pacchetto NPM:** [olostep-cli](https://www.npmjs.com/package/olostep-cli)
**Repository:** [github.com/olostep-api/olostep-cli](https://github.com/olostep-api/olostep-cli)

CLI per l'[Olostep API](https://www.olostep.com/) — **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+**.

<Tabs>
  <Tab title="npm (consigliato)">
    ```bash theme={null}
    npm install -g olostep-cli
    olostep init
    ```
  </Tab>

  <Tab title="One-liner (macOS / Linux)">
    ```bash theme={null}
    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.
  </Tab>

  <Tab title="One-liner (Windows)">
    ```powershell theme={null}
    iwr -useb https://olostep.com/install.ps1 | iex
    olostep init
    ```

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

  <Tab title="No-install (npx)">
    ```bash theme={null}
    npx -y olostep-cli@latest --help
    ```

    Ottimo per provare un singolo comando senza un'installazione globale.
  </Tab>
</Tabs>

`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:

```bash theme={null}
olostep init
```

Flag: `--skills-only`, `--mcp-only`, `--no-browser`, `--relogin`.

Per **solo autenticarsi** (senza competenze/MCP):

```bash theme={null}
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:

```bash theme={null}
export OLOSTEP_API_KEY=your_key_here
```

Ottieni una chiave dalla [dashboard delle chiavi API](https://www.olostep.com/dashboard/api-keys).

**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

```bash theme={null}
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

```bash theme={null}
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](/features/search)                    |
| Ottenere una risposta ricercata | `answer`                        | [Answers](/features/answers)                    |
| Scoprire URL su un sito         | `map`                           | [Maps](/features/maps)                          |
| Estrarre una pagina             | `scrape`                        | [Scrapes](/features/scrapes)                    |
| Estrarre ogni pagina su un sito | `crawl`                         | [Crawls](/features/crawls)                      |
| Estrarre molti URL da un CSV    | `batch-scrape`                  | [Batches](/features/batches)                    |
| Estrarre campi strutturati      | `--parser-id` su `batch-scrape` | [Parsers](/features/structured-content/parsers) |
| Rieseguire un risultato per ID  | `scrape-get`                    | [Scrapes](/features/scrapes)                    |
| Taggare/organizzare un batch    | `batch-update`                  | [Batches](/features/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.

```bash theme={null}
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                        |

```bash theme={null}
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 |

```bash theme={null}
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                  |

```bash theme={null}
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](/features/scrapes#caching)) |

```bash theme={null}
olostep scrape "https://example.com" --formats markdown,html
olostep scrape "https://example.com" --payload-file options.json --out -
```

### `scrape-get`: recupera per ID

```bash theme={null}
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`.

```bash theme={null}
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`**.

```csv theme={null}
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                        |

```bash theme={null}
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).

```bash theme={null}
olostep batch-update "batch_abc123" --metadata-json '{"team":"growth"}'
olostep batch-update "batch_abc123" --metadata-file meta.json
```

## Comandi di autenticazione

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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](/features/skills) per l'elenco completo e le opzioni.

## Controlli di salute

```bash theme={null}
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:

```bash theme={null}
olostep doctor --json --skip-network | jq 'select(.status == "fail")'
```

## Versione e aggiornamenti

```bash theme={null}
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:

```powershell theme={null}
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

```bash theme={null}
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](/features/maps) · [Crawls](/features/crawls) · [Batches](/features/batches) · [Answers](/features/answers) · [Searches](/features/search) · [Skills](/features/skills) · [MCP Server](/integrations/mcp-server)