EnConvert CLI — Command-Line File Conversion & Web Data#

enconvert is the official command-line interface for the EnConvert API — convert files across 46 upload routes, render URLs and whole sites to PDF or screenshots, and pull agent-ready web data (perceive, discover, lookup, distill, ingest) without leaving your terminal. It installs from Homebrew, a sha256-verified install script, Scoop, or npm, ships with zero telemetry, and is built for scripting end to end: --json on every command, a built-in --jq filter, deterministic exit codes, and converted files saved to disk with the path printed on stdout.

Install#

Homebrew (macOS and Linux):

brew install enconvert/tap/enconvert

Install script (macOS and Linux, sha256-verified):

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

npm i -g @enconvert/cli

Check the install with enconvert --version, then explore everything the binary can do with enconvert --help.

Authenticate#

enconvert auth login

Paste your private API key (sk_live_...) — hidden input, validated live against the API, and stored in credentials.toml with file mode 0600. Every request authenticates with the X-API-Key header. In CI, skip login and set ENCONVERT_API_KEY instead.

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 prints the active key for piping into other tools — nothing else ever echoes it.

Convert files#

enconvert convert covers all 46 upload routes — data formats, office documents, images, universal targets, and compression. The endpoint is inferred from the file extension plus --to:

Globs fan out into one conversion per file, and -o - streams raw bytes for piping:

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

By default the converted file is downloaded to disk and its path is printed on stdout. -o out.pdf chooses the destination, -O keeps the server filename, --url-only prints the presigned URL without downloading, and -o - writes the raw bytes to stdout instead.

enconvert formats lists every supported route; enconvert params <route> shows the parameters a specific endpoint accepts.

Render URLs & sites#

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

Whole sites run as asynchronous batches. By default the CLI waits and shows progress; --no-wait prints the batch id and returns immediately:

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

Web data for agents#

The V2 commands map 1:1 to the V2 web-intelligence endpoints:

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 renders one page into markdown, HTML, screenshot, and PDF artifacts in a single call; discover enumerates a site's URLs without rendering; lookup runs a web, news, scholar, or maps search; distill extracts structured data matching your JSON schema; and ingest crawls a site into RAG-ready chunked JSONL. Ingest jobs bring their own helpers — enconvert ingest list, enconvert ingest files <job_id>, enconvert ingest webhook-secret — and any produced artifact can be fetched with enconvert files download <id>.

Working inside an AI assistant instead of a terminal? enconvert mcp install wires up the EnConvert MCP server for you.

Jobs & scripting#

Every command accepts --json (a single JSON document), --jsonl (streaming lines), a built-in --jq filter, and --template for custom text output:

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

Async work follows a start / wait / fetch pattern:

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 makes waiting commands exit with the job's outcome, --poll-interval tunes the polling cadence, --dry-run prints the request without sending it, and --no-input disables every prompt for CI. Exit codes are stable and script-friendly:

The api command#

A gh-style passthrough that reaches every EnConvert endpoint — including new ones the CLI has no dedicated verb for yet:

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

-f adds string fields, -F adds typed magic fields (numbers, booleans, @file to read a value from disk). With fields the request is a POST, without them a GET, and --jq filters the JSON response inline.

Configuration & profiles#

Settings live in ~/.config/enconvert/config.toml as named profiles; keys live separately in credentials.toml (mode 0600); a project-local .enconvertrc.toml overrides both:

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

[profile.work]
timeout = 120

Select a profile per invocation with --profile work, per shell with ENCONVERT_PROFILE, or persistently with enconvert auth switch. enconvert config reads and writes any setting from the command line.

Environment variables#

Flags beat environment variables, which beat the project .enconvertrc.toml, which beats the global config.

Shell completion#

source <(enconvert completion zsh)

Add that line to your shell profile. bash, fish, and powershell completions are generated the same way.

Updating#

enconvert upgrade

Detects how the CLI was installed (Homebrew, install script, Scoop, npm) and upgrades through the same channel. Set ENCONVERT_NO_UPDATE_NOTIFIER=1 to silence the once-a-day update notice.

Uninstall#

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

Optionally remove ~/.config/enconvert/ to delete config and credentials.

Troubleshooting#

command not found: enconvert after npm i -g. The npm build requires Node.js >= 22.12, and npm's global bin directory must be on your PATH — check it with npm prefix -g. The Homebrew, install-script, and Scoop builds are self-contained binaries with no Node requirement.

A redirected file contains a file path instead of the document. By default the CLI downloads the file to disk and prints the path on stdout — enconvert url pdf ... > out.pdf captures that path text. Stream the actual bytes with -o -, or set the destination with -o out.pdf.

Exit code 4 in CI. No usable API key. Set ENCONVERT_API_KEY in your CI secrets; enconvert auth status shows exactly where the key is (or is not) coming from.

A command hangs in CI. It is waiting on an interactive prompt. Pass --no-input (or set ENCONVERT_NO_INPUT=1) so prompts fail fast instead of blocking.

Links#

• npm — @enconvert/cli
• GitHub — enconvert/cli (MIT, zero telemetry)
• MCP server — @enconvert/mcp setup
• API reference — Endpoints overview
• Error codes — Error codes reference