API Documentation

EnConvert CLI — Dateikonvertierung & Web-Daten von der Kommandozeile#

enconvert ist die offizielle Kommandozeilen-Schnittstelle für die EnConvert-API — konvertieren Sie Dateien über 46 Upload-Routen, rendern Sie URLs und ganze Websites als PDF oder Screenshot und holen Sie agentenfertige Web-Daten (perceive, discover, lookup, distill, ingest), ohne Ihr Terminal zu verlassen. Die CLI wird über Homebrew, ein sha256-verifiziertes Install-Skript, Scoop oder npm installiert, enthält null Telemetrie und ist durchgehend fürs Scripting gebaut: --json bei jedem Befehl, ein eingebauter --jq-Filter, deterministische Exit-Codes, und konvertierte Dateien landen auf der Festplatte, während der Pfad auf stdout ausgegeben wird.

npm: @enconvert/cli · Quelle: enconvert/cli · Lizenz: MIT · Telemetrie: keine

Installation#

Homebrew (macOS und Linux):

brew install enconvert/tap/enconvert

Install-Skript (macOS und Linux, sha256-verifiziert):

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 (jede Plattform, Node.js >= 22.12):

npm i -g @enconvert/cli

Prüfen Sie die Installation mit enconvert --version und erkunden Sie den vollen Funktionsumfang mit enconvert --help.

Authentifizierung#

enconvert auth login

Fügen Sie Ihren privaten API-Schlüssel ein (sk_live_...) — verdeckte Eingabe, live gegen die API validiert und in credentials.toml mit Dateimodus 0600 gespeichert. Jede Anfrage authentifiziert sich über den X-API-Key-Header. In CI überspringen Sie login und setzen stattdessen 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 gibt den aktiven Schlüssel aus, um ihn an andere Tools weiterzureichen — kein anderer Befehl zeigt ihn jemals an.

Dateien konvertieren#

enconvert convert deckt alle 46 Upload-Routen ab — Datenformate, Office-Dokumente, Bilder, universelle Ziele und Komprimierung. Der Endpunkt wird aus der Dateiendung plus --to abgeleitet:

Konvertierung Befehl Aufgerufener Endpunkt
DOCX → PDF enconvert convert report.docx --to pdf POST /v1/convert/doc-to-pdf
HEIC → WebP enconvert convert photo.heic --to webp POST /v1/convert/heic-to-webp
JSON → YAML enconvert convert data.json --to yaml POST /v1/convert/json-to-yaml
Markdown → PDF enconvert convert README.md --to pdf POST /v1/convert/markdown-to-pdf

Globs fächern sich in eine Konvertierung pro Datei auf, und -o - streamt Roh-Bytes für Pipes:

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

Standardmäßig wird die konvertierte Datei auf die Festplatte geladen und ihr Pfad auf stdout ausgegeben. -o out.pdf wählt das Ziel, -O behält den Server-Dateinamen, --url-only gibt nur die vorsignierte URL aus, ohne herunterzuladen, und -o - schreibt stattdessen die Roh-Bytes auf stdout.

enconvert formats listet jede unterstützte Route; enconvert params <route> zeigt die Parameter, die ein bestimmter Endpunkt akzeptiert.

URLs & Websites rendern#

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

Ganze Websites laufen als asynchrone Batches. Standardmäßig wartet die CLI und zeigt den Fortschritt; --no-wait gibt die Batch-ID aus und kehrt sofort zurück:

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

Web-Daten für Agenten#

Die V2-Befehle bilden 1:1 die V2-Web-Intelligence-Endpunkte ab:

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 rendert eine Seite in einem einzigen Aufruf zu Markdown-, HTML-, Screenshot- und PDF-Artefakten; discover zählt die URLs einer Website ohne Rendering auf; lookup führt eine Web-, News-, Scholar- oder Maps-Suche aus; distill extrahiert strukturierte Daten passend zu Ihrem JSON-Schema; und ingest crawlt eine Website in RAG-fertiges, gechunktes JSONL. Ingest-Jobs bringen eigene Helfer mit — enconvert ingest list, enconvert ingest files <job_id>, enconvert ingest webhook-secret — und jedes erzeugte Artefakt lässt sich mit enconvert files download <id> abrufen.

Sie arbeiten in einem KI-Assistenten statt im Terminal? enconvert mcp install richtet den EnConvert-MCP-Server für Sie ein.

Jobs & Scripting#

Jeder Befehl akzeptiert --json (ein einzelnes JSON-Dokument), --jsonl (Streaming-Zeilen), einen eingebauten --jq-Filter und --template für eigene Textausgaben:

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

Asynchrone Arbeit folgt einem Start-/Warten-/Abholen-Muster:

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 lässt wartende Befehle mit dem Ergebnis des Jobs beenden, --poll-interval steuert den Polling-Takt, --dry-run gibt die Anfrage aus, ohne sie zu senden, und --no-input deaktiviert jede Eingabeaufforderung für CI. Die Exit-Codes sind stabil und skriptfreundlich:

Code Bedeutung
0 Erfolg
2 Bedienfehler — ungültige Flags oder Argumente
4 Authentifizierung fehlgeschlagen
5 Rate-Limit überschritten
6 Plan- oder Kontingentgrenze erreicht
7 Nicht unterstützte Konvertierung oder Format
8 Eingabe abgelehnt
9 Serverfehler oder Job-Fehlschlag
10 Netzwerkfehler oder Timeout
130 Mit Strg-C abgebrochen

Der Befehl api#

Ein Passthrough im gh-Stil, der jeden EnConvert-Endpunkt erreicht — auch neue, für die die CLI noch kein eigenes Verb hat:

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

-f fügt String-Felder hinzu, -F fügt typisierte Magic-Felder hinzu (Zahlen, Booleans, @file zum Einlesen eines Werts von der Festplatte). Mit Feldern ist die Anfrage ein POST, ohne sie ein GET, und --jq filtert die JSON-Antwort direkt.

Konfiguration & Profile#

Einstellungen liegen als benannte Profile in ~/.config/enconvert/config.toml; Schlüssel liegen separat in credentials.toml (Modus 0600); eine projektlokale .enconvertrc.toml überschreibt beides:

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

[profile.work]
timeout = 120

Wählen Sie ein Profil pro Aufruf mit --profile work, pro Shell mit ENCONVERT_PROFILE oder dauerhaft mit enconvert auth switch. enconvert config liest und schreibt jede Einstellung von der Kommandozeile aus.

Umgebungsvariablen#

Variable Zweck
ENCONVERT_API_KEY API-Schlüssel — überschreibt gespeicherte Zugangsdaten
ENCONVERT_API_URL Override der API-Basis-URL
ENCONVERT_PROFILE Name des aktiven Profils
ENCONVERT_CONFIG Expliziter Pfad zur Konfigurationsdatei
ENCONVERT_CONFIG_DIR Override des Konfigurationsverzeichnisses
ENCONVERT_DEBUG Ausführliches Request- und Response-Logging
ENCONVERT_NO_INPUT Interaktive Eingabeaufforderungen deaktivieren
ENCONVERT_NO_UPDATE_NOTIFIER Update-Hinweis stummschalten
NO_COLOR Farbige Ausgabe deaktivieren (die NO_COLOR-Familie wird respektiert)

Flags schlagen Umgebungsvariablen, diese schlagen die projektlokale .enconvertrc.toml, und diese schlägt die globale Konfiguration.

Shell-Vervollständigung#

source <(enconvert completion zsh)

Fügen Sie diese Zeile Ihrem Shell-Profil hinzu. Vervollständigungen für bash, fish und powershell werden auf dieselbe Weise erzeugt.

Aktualisieren#

enconvert upgrade

Erkennt, wie die CLI installiert wurde (Homebrew, Install-Skript, Scoop, npm), und aktualisiert über denselben Kanal. Setzen Sie ENCONVERT_NO_UPDATE_NOTIFIER=1, um den täglichen Update-Hinweis stummzuschalten.

Deinstallation#

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

Entfernen Sie optional ~/.config/enconvert/, um Konfiguration und Zugangsdaten zu löschen.

Fehlerbehebung#

command not found: enconvert nach npm i -g. Der npm-Build erfordert Node.js >= 22.12, und das globale bin-Verzeichnis von npm muss in Ihrem PATH liegen — prüfen Sie es mit npm prefix -g. Die Homebrew-, Install-Skript- und Scoop-Builds sind eigenständige Binaries ohne Node-Voraussetzung.

Eine umgeleitete Datei enthält einen Dateipfad statt des Dokuments. Standardmäßig lädt die CLI die Datei auf die Festplatte und gibt den Pfad auf stdout aus — enconvert url pdf ... > out.pdf fängt diesen Pfadtext ein. Streamen Sie die eigentlichen Bytes mit -o - oder setzen Sie das Ziel mit -o out.pdf.

Exit-Code 4 in CI. Kein nutzbarer API-Schlüssel. Setzen Sie ENCONVERT_API_KEY in Ihren CI-Secrets; enconvert auth status zeigt genau, woher der Schlüssel kommt (oder nicht kommt).

Ein Befehl hängt in CI. Er wartet auf eine interaktive Eingabe. Übergeben Sie --no-input (oder setzen Sie ENCONVERT_NO_INPUT=1), damit Eingabeaufforderungen sofort fehlschlagen statt zu blockieren.

← Node.js MCP Server →