EnConvert CLI — Conversión de archivos y datos web desde la línea de comandos#

enconvert es la interfaz de línea de comandos oficial de la API de EnConvert — convierte archivos a través de 46 rutas de subida, renderiza URLs y sitios completos a PDF o capturas de pantalla, y obtén datos web listos para agentes (perceive, discover, lookup, distill, ingest) sin salir de tu terminal. Se instala desde Homebrew, un script de instalación verificado con sha256, Scoop o npm, no incluye telemetría alguna y está construida para scripting de principio a fin: --json en cada comando, un filtro --jq integrado, códigos de salida deterministas y archivos convertidos guardados en disco con la ruta impresa en stdout.

Instalación#

Homebrew (macOS y Linux):

brew install enconvert/tap/enconvert

Script de instalación (macOS y Linux, verificado con sha256):

curl -fsSL https://get.enconvert.com/install.sh | sh

Scoop (Windows):

scoop bucket add enconvert https://github.com/enconvert/scoop-bucket && scoop install enconvert

npm (cualquier plataforma, Node.js >= 22.12):

npm i -g @enconvert/cli

Comprueba la instalación con enconvert --version y explora todo lo que puede hacer el binario con enconvert --help.

Autenticación#

enconvert auth login

Pega tu clave API privada (sk_live_...) — entrada oculta, validada en vivo contra la API y almacenada en credentials.toml con modo de archivo 0600. Cada petición se autentica con la cabecera X-API-Key. En CI, omite login y define ENCONVERT_API_KEY en su lugar.

enconvert auth status     # where the key comes from, plan, quota
enconvert whoami          # one-line identity check
enconvert usage           # current-period conversion and V2 usage
enconvert auth switch     # change the active profile
enconvert auth logout     # delete the stored key

enconvert auth token imprime la clave activa para encadenarla a otras herramientas — ningún otro comando la muestra jamás.

Convertir archivos#

enconvert convert cubre las 46 rutas de subida — formatos de datos, documentos de oficina, imágenes, destinos universales y compresión. El endpoint se infiere de la extensión del archivo más --to:

Los globs se despliegan en una conversión por archivo, y -o - transmite bytes crudos para encadenar:

enconvert convert *.heic --to webp
enconvert convert data.csv --to json -o - | jq '.[0]'

Por defecto, el archivo convertido se descarga a disco y su ruta se imprime en stdout. -o out.pdf elige el destino, -O conserva el nombre de archivo del servidor, --url-only imprime la URL prefirmada sin descargar, y -o - escribe los bytes crudos en stdout en su lugar.

enconvert formats lista todas las rutas soportadas; enconvert params <route> muestra los parámetros que acepta un endpoint concreto.

Renderizar URLs y sitios#

enconvert url pdf https://example.com -o page.pdf      # POST /v1/convert/url-to-pdf
enconvert url screenshot https://example.com           # POST /v1/convert/url-to-screenshot
enconvert url markdown https://example.com/article     # POST /v1/convert/url-to-markdown

Los sitios completos se ejecutan como lotes asíncronos. Por defecto la CLI espera y muestra el progreso; --no-wait imprime el id del lote y retorna de inmediato:

enconvert site pdf https://example.com
enconvert site screenshot https://example.com --no-wait

Datos web para agentes#

Los comandos V2 se corresponden 1:1 con los endpoints de inteligencia web V2:

enconvert perceive https://example.com                               # POST /v2/perceive
enconvert perceive batch urls.txt                                    # async batch, up to 1000 URLs
enconvert discover https://example.com                               # POST /v2/discover
enconvert lookup "best static site generators"                       # POST /v2/lookup
enconvert distill https://example.com/pricing --schema schema.json   # POST /v2/distill
enconvert ingest https://docs.example.com                            # POST /v2/ingest

perceive renderiza una página en artefactos de markdown, HTML, captura y PDF en una sola llamada; discover enumera las URLs de un sitio sin renderizar; lookup ejecuta una búsqueda web, de noticias, académica o de mapas; distill extrae datos estructurados conforme a tu esquema JSON; e ingest rastrea un sitio hacia JSONL troceado listo para RAG. Los trabajos de ingest traen sus propios auxiliares — enconvert ingest list, enconvert ingest files <job_id>, enconvert ingest webhook-secret — y cualquier artefacto producido puede obtenerse con enconvert files download <id>.

¿Trabajas dentro de un asistente de IA en lugar de un terminal? enconvert mcp install configura el servidor MCP de EnConvert por ti.

Jobs y scripting#

Cada comando acepta --json (un único documento JSON), --jsonl (líneas en streaming), un filtro --jq integrado y --template para salida de texto personalizada:

enconvert jobs get <job_id> --json --jq .status

El trabajo asíncrono sigue un patrón de iniciar / esperar / recoger:

enconvert site pdf https://example.com --no-wait
enconvert jobs batch <batch_id>
enconvert jobs wait <batch_id> --wait-timeout 600 --exit-status

--exit-status hace que los comandos en espera terminen con el resultado del trabajo, --poll-interval ajusta la cadencia de sondeo, --dry-run imprime la petición sin enviarla, y --no-input desactiva todos los avisos interactivos para CI. Los códigos de salida son estables y aptos para scripts:

El comando api#

Un passthrough al estilo de gh que alcanza cualquier endpoint de EnConvert — incluidos los nuevos para los que la CLI aún no tiene verbo dedicado:

enconvert api /v2/perceive -f url=https://example.com
enconvert api /v1/convert/status/<job_id> --jq .status

-f añade campos de cadena, -F añade campos mágicos tipados (números, booleanos, @file para leer un valor desde disco). Con campos la petición es un POST, sin ellos un GET, y --jq filtra la respuesta JSON al vuelo.

Configuración y perfiles#

Los ajustes viven en ~/.config/enconvert/config.toml como perfiles con nombre; las claves viven aparte en credentials.toml (modo 0600); un .enconvertrc.toml local del proyecto sobrescribe ambos:

[profile.default]
api_url = "https://api.enconvert.com"

[profile.work]
timeout = 120

Selecciona un perfil por invocación con --profile work, por shell con ENCONVERT_PROFILE, o de forma persistente con enconvert auth switch. enconvert config lee y escribe cualquier ajuste desde la línea de comandos.

Variables de entorno#

Los flags ganan a las variables de entorno, que ganan al .enconvertrc.toml del proyecto, que gana a la configuración global.

Autocompletado del shell#

source <(enconvert completion zsh)

Añade esa línea a tu perfil del shell. Los autocompletados de bash, fish y powershell se generan de la misma manera.

Actualización#

enconvert upgrade

Detecta cómo se instaló la CLI (Homebrew, script de instalación, Scoop, npm) y actualiza por el mismo canal. Define ENCONVERT_NO_UPDATE_NOTIFIER=1 para silenciar el aviso de actualización diario.

Desinstalación#

brew uninstall enconvert          # Homebrew
scoop uninstall enconvert         # Scoop
npm rm -g @enconvert/cli          # npm
rm "$(command -v enconvert)"      # install script

Opcionalmente elimina ~/.config/enconvert/ para borrar la configuración y las credenciales.

Solución de problemas#

command not found: enconvert tras npm i -g. La build de npm requiere Node.js >= 22.12, y el directorio bin global de npm debe estar en tu PATH — compruébalo con npm prefix -g. Las builds de Homebrew, script de instalación y Scoop son binarios autocontenidos sin requisito de Node.

Un archivo redirigido contiene una ruta de archivo en lugar del documento. Por defecto la CLI descarga el archivo a disco e imprime la ruta en stdout — enconvert url pdf ... > out.pdf captura ese texto de ruta. Transmite los bytes reales con -o -, o fija el destino con -o out.pdf.

Código de salida 4 en CI. No hay clave API utilizable. Define ENCONVERT_API_KEY en los secretos de tu CI; enconvert auth status muestra exactamente de dónde viene (o no viene) la clave.

Un comando se queda colgado en CI. Está esperando un aviso interactivo. Pasa --no-input (o define ENCONVERT_NO_INPUT=1) para que los avisos fallen rápido en lugar de bloquear.

Enlaces#

• npm — @enconvert/cli
• GitHub — enconvert/cli (MIT, sin telemetría)
• Servidor MCP — @enconvert/mcp setup
• Referencia de la API — Resumen de endpoints
• Códigos de error — Referencia de códigos de error