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

> Interfaz de línea de comandos para scrape, search, map, crawl, answers y batches — salida JSON para scripts, CI y agentes de IA

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

CLI para la [Olostep API](https://www.olostep.com/) — **scrape**, **search**, **map**, **crawl**, **answer** y **batch** la web desde tu terminal. Cada comando devuelve **JSON** para que se pueda canalizar limpiamente en `jq`, agentes y CI.

JavaScript puro, Node 18+, sin binarios nativos para descargar. Se instala en menos de un segundo, inicia en \~200 ms, se entrega como un único paquete de \~100 KB.

## Instalación

**Requisitos:** Node.js **18+**.

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

  <Tab title="Una línea (macOS / Linux)">
    ```bash theme={null}
    curl -fsSL https://olostep.com/install.sh | sh
    olostep init
    ```

    El script verifica Node 18+, ejecuta `npm install -g olostep-cli`, y recurre a `sudo` si es necesario.
  </Tab>

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

    La misma idea que el script de macOS/Linux, pero para PowerShell.
  </Tab>

  <Tab title="Sin instalación (npx)">
    ```bash theme={null}
    npx -y olostep-cli@latest --help
    ```

    Bueno para probar un solo comando sin una instalación global.
  </Tab>
</Tabs>

`olostep init` es el siguiente paso recomendado — te inicia sesión, instala las habilidades de Olostep en tus agentes de IA, y configura el servidor MCP, todo en un solo comando. Los scripts de una línea envuelven `npm install -g olostep-cli` con una verificación de Node 18+ y un recurso a `sudo`, por lo que funcionan incluso si no estás seguro de tu configuración local.

**Plataformas:** macOS (Apple Silicon e Intel), Linux (x64 y arm64), Windows (x64 y arm64).

## Configuración

Un comando lo hace todo — iniciar sesión, instalar habilidades e instalar el servidor MCP:

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

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

Para **solo iniciar sesión** (sin habilidades/MCP):

```bash theme={null}
olostep login
olostep login --no-browser     # imprime la URL (útil sobre SSH)
```

El navegador se abre en la página de autenticación de Olostep; haces clic en **Autorizar**, y el CLI guarda tu clave localmente.

**Alternativa — establece una variable de entorno.** Bueno para CI:

```bash theme={null}
export OLOSTEP_API_KEY=tu_clave_aquí
```

Obtén una clave desde el [panel de claves API](https://www.olostep.com/dashboard/api-keys).

**Dónde se almacena la clave** (después de `olostep login`):

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

## Cerrar sesión

```bash theme={null}
olostep logout            # solicita confirmación, luego elimina credentials.json
olostep logout --dry-run  # solo vista previa — ver qué sucedería
olostep logout --yes      # omitir la confirmación (para scripts)
olostep logout --json     # salida legible por máquina
```

`logout` también te advierte si las variables de entorno `OLOSTEP_API_KEY` / `OLOSTEP_API_TOKEN` o un archivo `.env` en tu directorio actual aún tienen una clave — esas tienen prioridad sobre el archivo de credenciales, por lo que eliminar solo el archivo puede no ser suficiente. La salida incluye los comandos exactos para desactivar en PowerShell y bash/zsh.

## Inicio rápido

```bash theme={null}
olostep login

olostep search "mejores APIs de scraping web 2025" --limit 5
olostep answer "¿Qué hace Olostep?"
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
```

Cada comando imprime su resultado JSON en stdout por defecto. Usa `--out <ruta>` para guardar en un archivo.

## ¿Qué puede hacer?

| Quieres…                             | Comando                         | Producto Olostep                                |
| ------------------------------------ | ------------------------------- | ----------------------------------------------- |
| Buscar en la web                     | `search`                        | [Searches](/features/search)                    |
| Obtener una respuesta investigada    | `answer`                        | [Answers](/features/answers)                    |
| Descubrir URLs en un sitio           | `map`                           | [Maps](/features/maps)                          |
| Extraer una página                   | `scrape`                        | [Scrapes](/features/scrapes)                    |
| Extraer cada página en un sitio      | `crawl`                         | [Crawls](/features/crawls)                      |
| Extraer muchas URLs de un CSV        | `batch-scrape`                  | [Batches](/features/batches)                    |
| Extraer campos estructurados         | `--parser-id` en `batch-scrape` | [Parsers](/features/structured-content/parsers) |
| Volver a obtener un resultado por ID | `scrape-get`                    | [Scrapes](/features/scrapes)                    |
| Etiquetar/organizar un lote          | `batch-update`                  | [Batches](/features/batches)                    |

## Salida

Cada comando **imprime su resultado JSON en stdout** por defecto.

| Flag           | Comportamiento                                            |
| -------------- | --------------------------------------------------------- |
| *(ninguno)*    | Imprimir JSON en **stdout** (UTF-8, con sangría)          |
| `--out <ruta>` | Escribir JSON en ese archivo en su lugar                  |
| `--out -`      | Explícitamente stdout (igual que el valor predeterminado) |

Las líneas de progreso y registro van a **stderr**, por lo que stdout permanece limpio para canalizaciones.

```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 "tema" --json | jq '.links[].url'
```

**Elegir entre ellos:**

* **`search`** — quieres una lista de URLs relevantes y fragmentos para una consulta. El CLI busca en la web por ti.
* **`answer`** — quieres una respuesta sintetizada, no contenido bruto de la página. El CLI hace la investigación por ti.
* **`scrape`** — ya tienes la URL y quieres contenido limpio.
* **`crawl`** — quieres cada página en un sitio (o un subconjunto filtrado) sin enumerar URLs a mano.
* **`batch-scrape`** — tienes una lista de URLs y quieres que se procesen en paralelo.

## Comandos

Usa `olostep <comando> --help` para cada opción.

### `search`: búsqueda web en vivo

Devuelve enlaces orgánicos deduplicados (URL, título, descripción).

| Opción              | Descripción                                             |
| ------------------- | ------------------------------------------------------- |
| `--limit`           | Número de resultados, por defecto 12, máximo 25         |
| `--include-domains` | Dominios separados por comas para restringir resultados |
| `--exclude-domains` | Dominios separados por comas para excluir               |
| `--out`             | Archivo o `-`                                           |
| `--json`            | Salida legible por máquina                              |

```bash theme={null}
olostep search "Herramientas CLI de TypeScript" --limit 10
olostep search "proyectos de código abierto" --include-domains "github.com" --limit 5
olostep search "agentes de IA" --json | jq '.links[].url'
```

### `answer`: respuesta investigada

Sincrónico — devuelve cuando la respuesta está lista.

| Opción          | Descripción                                  |
| --------------- | -------------------------------------------- |
| `--out`         | Archivo o `-`                                |
| `--json-format` | Forma JSON opcional para salida estructurada |

```bash theme={null}
olostep answer "¿Qué construye esta empresa?" --out answer.json
olostep answer "Extraer hechos" --json-format '{"empresa":"","año":""}' --out -
```

### `map`: descubrir URLs

| Opción                                           | Descripción                                    |
| ------------------------------------------------ | ---------------------------------------------- |
| `--out`                                          | Ruta del archivo o `-`                         |
| `--top-n`                                        | Máximo de URLs a devolver                      |
| `--search-query`                                 | Consulta opcional para guiar el descubrimiento |
| `--include-subdomain` / `--no-include-subdomain` | Subdominios                                    |
| `--include-url` / `--exclude-url`                | Patrones de URL repetibles                     |
| `--cursor`                                       | Cursor de paginación                           |

```bash theme={null}
olostep map "https://example.com" --top-n 100 --search-query "blog"
```

### `scrape`: una URL

**Formatos:** `html`, `markdown`, `text`, `json`, `raw_pdf`, `screenshot` (separados por comas; por defecto `markdown`).

| Opción                              | Descripción                                                                                                                                         |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--formats`                         | Separados por comas                                                                                                                                 |
| `--country`                         | Código de país (por ejemplo, `US`, `GB`)                                                                                                            |
| `--wait-before-scraping`            | Esperar antes de extraer (ms)                                                                                                                       |
| `--payload-json` / `--payload-file` | Opciones avanzadas como JSON (por ejemplo, `"max_age": 86400` para optar por el almacenamiento en caché — ver [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`: obtener por ID

```bash theme={null}
olostep scrape-get "scrape_abc123" --out -
```

### `crawl`: todo el sitio

Inicia un rastreo, consulta hasta que termine, luego recupera el contenido de las páginas.

**Recuperar formatos:** `markdown`, `html`, `json`.

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

El CSV debe tener una fila de encabezado con columnas **`custom_id`** (o `id`) y **`url`**.

```csv theme={null}
custom_id,url
example,https://example.com
iana,https://iana.org
docs,https://docs.olostep.com
```

| Opción                                           | Descripción                                      |
| ------------------------------------------------ | ------------------------------------------------ |
| `--formats`                                      | `markdown`, `html`, `json` (separados por comas) |
| `--country`                                      | Código de país opcional                          |
| `--parser-id`                                    | ID del analizador para extracción estructurada   |
| `--poll-seconds`, `--log-every`, `--items-limit` | Consulta y paginación                            |
| `--dry-run`                                      | Imprimir carga útil y salir                      |

```bash theme={null}
olostep batch-scrape urls.csv --formats markdown,html
olostep batch-scrape urls.csv --parser-id "<PARSER_ID>" --out results.json
```

Sincrónico — consulta hasta que el lote se complete, luego recupera cada elemento.

### `batch-update`: metadatos del lote

Requiere **uno de** `--metadata-json` o `--metadata-file` (objeto JSON).

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

## Comandos de autenticación

```bash theme={null}
olostep login                      # inicio de sesión PKCE en el navegador
olostep logout                     # eliminar credenciales guardadas
olostep status                     # mostrar estado de autenticación, rutas de configuración, versión

olostep auth login                 # igual que olostep login
olostep auth logout                # igual que olostep logout
olostep auth status                # igual que olostep status
olostep auth set-key <key>         # guardar una clave API directamente (sin navegador)
```

`auth set-key` es útil para CI y scripts — escribe la clave directamente sin pasar por el flujo del navegador.

## Instalar el servidor MCP

El CLI escribe el servidor Olostep MCP en la configuración de tu agente — sin edición de JSON.

```bash theme={null}
olostep mcp install                          # detectar agentes, punto final alojado
olostep mcp install --agent cursor           # solo Cursor
olostep mcp install --transport stdio        # npx local en lugar de alojado
olostep mcp install --no-global              # escribir en el proyecto actual
olostep mcp install --dry-run --json         # solo plan
olostep mcp uninstall                        # eliminar la entrada de olostep
olostep list mcp                             # mostrar qué agentes lo tienen
```

| Opción                             | Descripción                                                                                                                                  |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `--agent`                          | Agente específico, repetible. Soportado: `cursor`, `claude`, `claude-desktop`, `windsurf`, `vscode`, `kilo`, `opencode`, `continue`, `codex` |
| `--all-agents` / `--no-all-agents` | Apuntar a cada agente detectado (por defecto)                                                                                                |
| `--transport`                      | `http` (alojado, recomendado) o `stdio` (local `npx olostep-mcp`)                                                                            |
| `--global` / `--no-global`         | Configuración por usuario (por defecto) vs local del proyecto                                                                                |
| `--api-key`                        | Clave para incrustar; por defecto a las credenciales resueltas                                                                               |
| `--dry-run`                        | Mostrar el plan sin escribir                                                                                                                 |
| `--json`                           | Salida legible por máquina                                                                                                                   |

El punto final alojado en `https://mcp.olostep.com/mcp` usa `Authorization: Bearer <key>` — no se requiere proceso local de Node. El CLI solo fusiona la clave `olostep` en tu configuración existente. Reinicia tu agente después de la instalación.

## Habilidades para agentes de IA

El CLI incluye **13 habilidades de Olostep** — archivos `SKILL.md` instalados en Claude Code, Cursor y otros agentes para que sepan qué puede hacer Olostep y cuándo usarlo.

```bash theme={null}
olostep add skills                     # instalar todas en cada agente detectado
olostep skills install                 # igual (alias)
olostep skills update                  # reinstalar / actualizar todas las habilidades
olostep skills list                    # ver qué está instalado y dónde
olostep skills uninstall               # eliminar todas las habilidades
```

Filtrar lo que se instala:

```bash theme={null}
olostep add skills --category usage    # solo habilidades básicas de datos web
olostep add skills --skill scrape --skill map
olostep add skills --agent cursor --agent claude
```

Consulta [Habilidades](/features/skills) para la lista completa y opciones.

## Comprobaciones de salud

```bash theme={null}
olostep doctor                         # ejecutar todas las comprobaciones
olostep doctor --skip-network          # solo autenticación + configuración, sin llamadas HTTP
olostep doctor --json                  # NDJSON — un registro por comprobación (bueno para CI)
olostep doctor --fail-on-warn          # salir con 1 también en advertencias
```

Comprobaciones: clave API presente, clave API alcanzable, punto final MCP alcanzable, archivo de configuración existe para cada agente detectado.

Uso en CI:

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

## Versión y actualizaciones

```bash theme={null}
olostep version                        # versión del CLI, versión de Node, canal
olostep version --json                 # legible por máquina: { cli, node, channel }
olostep update                         # actualizar a la última versión (npm install -g olostep-cli@latest)
olostep update --check                 # comprobar si hay una versión más nueva disponible, no instalar
```

## Variables de entorno

| Variable                    | Efecto                                                              |
| --------------------------- | ------------------------------------------------------------------- |
| `OLOSTEP_API_KEY`           | Clave API                                                           |
| `OLOSTEP_API_TOKEN`         | Clave API (alias heredado)                                          |
| `OLOSTEP_JSON=1`            | Forzar salida JSON en cada comando (igual que `--json` globalmente) |
| `OLOSTEP_NO_UPDATE_CHECK=1` | Silenciar el aviso de "actualización disponible"                    |
| `OLOSTEP_CLI_CONFIG_DIR`    | Sobrescribir el directorio de credenciales                          |

## Notas para Windows / PowerShell

PowerShell tokeniza `,` y `*` de manera diferente a bash — cita los argumentos:

```powershell theme={null}
olostep scrape "https://example.com" --formats "markdown,html"
olostep map   "https://example.com" --include-url "/*"
olostep answer "Extraer hechos" --json-format '{"empresa":"","año":""}'
```

Las comillas simples son más seguras para valores JSON (sin interpolación de `$`).

## Ver qué está instalado

```bash theme={null}
olostep list skills    # habilidades de Olostep instaladas y qué agentes las tienen
olostep list mcp       # qué agentes tienen el servidor MCP de Olostep, y el transporte
```

## Flags globales

| Flag              | Descripción |
| ----------------- | ----------- |
| `-V`, `--version` | Versión     |
| `-h`, `--help`    | Ayuda       |

`--out`, `--timeout`, y `--api-key` están disponibles en cada comando de datos.

## Seguridad

Mantén las claves API fuera del control de versiones; rota si se filtran. `olostep logout` elimina el archivo de credenciales local y te informa si alguna fuente de variable de entorno aún tiene una clave.

## Relacionado

* [Maps](/features/maps) · [Crawls](/features/crawls) · [Batches](/features/batches) · [Answers](/features/answers) · [Searches](/features/search) · [Skills](/features/skills) · [MCP Server](/integrations/mcp-server)