EnConvert CLI: conversione file e dati web dalla riga di comando#

enconvert è l'interfaccia a riga di comando ufficiale dell'API EnConvert. Converte file attraverso 46 route di upload, trasforma URL e interi siti in PDF o screenshot e ottiene dati web pronti per gli agenti (perceive, discover, lookup, distill, ingest) senza farti uscire dal terminale. Si installa da Homebrew, da uno script di installazione verificato con sha256, da Scoop o da npm, non include alcuna telemetria ed è costruita per lo scripting da cima a fondo: --json su ogni comando, un filtro --jq integrato, codici di uscita deterministici e file convertiti salvati su disco con il percorso stampato su stdout.

Installazione#

Homebrew (macOS e Linux):

brew install enconvert/tap/enconvert

Script di installazione (macOS e Linux, verificato 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 (qualsiasi piattaforma, Node.js >= 22.12):

npm i -g @enconvert/cli

Verifica l'installazione con enconvert --version, poi esplora tutto ciò che il binario sa fare con enconvert --help.

Autenticazione#

enconvert auth login

Incolla la tua chiave API privata (sk_...). L'input resta nascosto, la chiave viene validata in tempo reale contro l'API e salvata in credentials.toml con modalità file 0600. Ogni richiesta si autentica con l'header X-API-Key. In CI salta login e imposta invece ENCONVERT_API_KEY.

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 stampa la chiave attiva per passarla ad altri strumenti, e nessun altro comando la mostra mai.

Convertire file#

enconvert convert copre tutte le 46 route di upload: formati di dati, documenti office, immagini, destinazioni universali e compressione. L'endpoint viene dedotto dall'estensione del file più --to:

I glob si espandono in una conversione per file, e -o - trasmette i byte grezzi per il piping:

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

Per impostazione predefinita il file convertito viene scaricato su disco e il suo percorso viene stampato su stdout. -o out.pdf sceglie la destinazione, -O mantiene il nome file del server, --url-only stampa l'URL prefirmato senza scaricare, e -o - scrive invece i byte grezzi su stdout.

enconvert formats elenca ogni route supportata; enconvert params <route> mostra i parametri accettati da uno specifico endpoint.

Renderizzare URL e siti#

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

I siti interi girano come batch asincroni. Per impostazione predefinita la CLI attende e mostra l'avanzamento; --no-wait stampa l'id del batch e ritorna subito:

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

Dati web per agenti#

I comandi V2 corrispondono 1:1 agli endpoint di web intelligence 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 trasforma una pagina in artefatti markdown, HTML, screenshot e PDF in una sola chiamata; discover enumera gli URL di un sito senza rendering; lookup esegue una ricerca web, news, scholar o maps; distill estrae dati strutturati conformi al tuo schema JSON; e ingest esegue il crawling di un sito in JSONL suddiviso in chunk pronto per il RAG. I job di ingest hanno i propri ausiliari (enconvert ingest list, enconvert ingest files <job_id>, enconvert ingest webhook-secret), e ogni artefatto prodotto si recupera con enconvert files download <id>.

Lavori dentro un assistente IA invece che in un terminale? enconvert mcp install configura per te il server MCP di EnConvert.

Job e scripting#

Ogni comando accetta --json (un singolo documento JSON), --jsonl (righe in streaming), un filtro --jq integrato e --template per un output di testo personalizzato:

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

Il lavoro asincrono segue uno schema avvia / attendi / recupera:

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 fa terminare i comandi in attesa con l'esito del job, --poll-interval regola la cadenza di polling, --dry-run stampa la richiesta senza inviarla, e --no-input disattiva ogni prompt per la CI. I codici di uscita sono stabili e adatti agli script:

Il comando api#

Un passthrough in stile gh che raggiunge ogni endpoint EnConvert, inclusi quelli nuovi per cui la CLI non ha ancora un verbo dedicato:

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

-f aggiunge campi stringa, -F aggiunge campi magici tipizzati (numeri, booleani, @file per leggere un valore dal disco). Con i campi la richiesta è una POST, senza è una GET, e --jq filtra la risposta JSON al volo.

Configurazione e profili#

Le impostazioni vivono in ~/.config/enconvert/config.toml come profili con nome; le chiavi vivono a parte in credentials.toml (modalità 0600); un .enconvertrc.toml locale al progetto sovrascrive entrambi:

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

[profile.work]
timeout = 120

Seleziona un profilo per invocazione con --profile work, per shell con ENCONVERT_PROFILE, o in modo persistente con enconvert auth switch. enconvert config legge e scrive qualsiasi impostazione dalla riga di comando.

Variabili d'ambiente#

I flag vincono sulle variabili d'ambiente, che vincono sul .enconvertrc.toml del progetto, che vince sulla configurazione globale.

Completamento della shell#

source <(enconvert completion zsh)

Aggiungi quella riga al profilo della tua shell. I completamenti bash, fish e powershell si generano allo stesso modo.

Aggiornamento#

enconvert upgrade

Rileva come è stata installata la CLI (Homebrew, script di installazione, Scoop, npm) e aggiorna attraverso lo stesso canale. Imposta ENCONVERT_NO_UPDATE_NOTIFIER=1 per silenziare l'avviso di aggiornamento giornaliero.

Disinstallazione#

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

Facoltativamente rimuovi ~/.config/enconvert/ per eliminare configurazione e credenziali.

Risoluzione dei problemi#

command not found: enconvert dopo npm i -g. La build npm richiede Node.js >= 22.12, e la directory bin globale di npm deve essere nel tuo PATH. Verifica la directory con npm prefix -g. Le build Homebrew, script di installazione e Scoop sono binari autonomi senza alcun requisito su Node.

Un file rediretto contiene un percorso di file invece del documento. Per impostazione predefinita la CLI scarica il file su disco e stampa il percorso su stdout, così enconvert url pdf ... > out.pdf cattura quel testo di percorso. Trasmetti i byte reali con -o -, oppure imposta la destinazione con -o out.pdf.

Codice di uscita 4 in CI. Nessuna chiave API utilizzabile. Imposta ENCONVERT_API_KEY nei secret della tua CI; enconvert auth status mostra esattamente da dove arriva (o non arriva) la chiave.

Un comando resta bloccato in CI. Sta aspettando un prompt interattivo. Passa --no-input (o imposta ENCONVERT_NO_INPUT=1) così i prompt falliscono subito invece di bloccare.

Link#

• npm: @enconvert/cli
• GitHub: enconvert/cli (MIT, zero telemetria)
• Server MCP: @enconvert/mcp setup
• Riferimento API: Panoramica degli endpoint
• Codici di errore: Riferimento codici di errore