EnConvert CLI — Conversione file e dati web dalla riga di comando#

enconvert è l'interfaccia a riga di comando ufficiale dell'API EnConvert — converti file attraverso 46 route di upload, trasforma URL e interi siti in PDF o screenshot e ottieni dati web pronti per gli agenti (perceive, discover, lookup, distill, ingest) senza 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_live_...) — input nascosto, 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 — 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 — verificala 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 — 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