---
seo_title: Command-Line File Conversion & Web Data CLI | EnConvert
meta_desc: Install the official enconvert CLI via Homebrew, curl, Scoop, or npm. Convert files, render URLs to PDF, and pull agent-ready web data from your terminal.
keywords: command line file conversion, cli convert files terminal, url to pdf command line, homebrew file converter cli, scoop file converter, npm cli file conversion, web data cli for agents, jq json output cli, enconvert cli
---

# 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.

<div class="alert alert-info">
<strong>npm:</strong> <code>@enconvert/cli</code> · <strong>Source:</strong> <a href="https://github.com/enconvert/cli">enconvert/cli</a> · <strong>License:</strong> MIT · <strong>Telemetry:</strong> zero
</div>

---

## Install

**Homebrew** (macOS and Linux):

```bash
brew install enconvert/tap/enconvert
```

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

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

**Scoop** (Windows):

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

**npm** (any platform, Node.js >= 22.12):

```bash
npm i -g @enconvert/cli
```

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

---

## Authenticate

```bash
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.

```bash
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`:

| Conversion | Command | Endpoint called |
|------------|---------|-----------------|
| 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 fan out into one conversion per file, and `-o -` streams raw bytes for piping:

```bash
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

```bash
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:

```bash
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:

```bash
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](/docs/mcp) 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:

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

Async work follows a start / wait / fetch pattern:

```bash
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:

| Code | Meaning |
|------|---------|
| `0` | Success |
| `2` | Usage error — bad flags or arguments |
| `4` | Authentication failed |
| `5` | Rate limit exceeded |
| `6` | Plan or quota limit reached |
| `7` | Unsupported conversion or format |
| `8` | Input rejected |
| `9` | Server error or job failure |
| `10` | Network error or timeout |
| `130` | Interrupted with Ctrl-C |

---

## The `api` command

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

```bash
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:

```toml
[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

| Variable | Purpose |
|----------|---------|
| `ENCONVERT_API_KEY` | API key — overrides stored credentials |
| `ENCONVERT_API_URL` | API base URL override |
| `ENCONVERT_PROFILE` | Active profile name |
| `ENCONVERT_CONFIG` | Explicit config file path |
| `ENCONVERT_CONFIG_DIR` | Config directory override |
| `ENCONVERT_DEBUG` | Verbose request and response logging |
| `ENCONVERT_NO_INPUT` | Disable interactive prompts |
| `ENCONVERT_NO_UPDATE_NOTIFIER` | Silence the update notice |
| `NO_COLOR` | Disable colored output (the NO_COLOR family is honored) |

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

---

## Shell completion

```bash
source <(enconvert completion zsh)
```

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

---

## Updating

```bash
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

```bash
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](https://www.npmjs.com/package/@enconvert/cli)
- **GitHub** — [enconvert/cli](https://github.com/enconvert/cli) (MIT, zero telemetry)
- **MCP server** — [@enconvert/mcp setup](/docs/mcp)
- **API reference** — [Endpoints overview](/docs/endpoints-overview)
- **Error codes** — [Error codes reference](/docs/error-codes)