Command Line

Convert files, folders and URLs with Docling for IBM watsonx from the terminal using docling convert-remote

docling convert-remote sends documents to Docling for IBM watsonx and writes the results next to you, in the same formats as a local docling convert. Nothing runs on your machine except the upload and the download, so you need no GPU and no models.

It is the simplest way to convert a folder of files from a shell script, and it is what the Agent Skills integration teaches an AI assistant to use.

Install

Install the lightweight client. It includes the docling command and does not download any models:

pip install docling-client

These packages also provide the same command and are valid alternatives:

Package	When to use it
`docling-client`	Recommended. Only what is needed to talk to the service
`docling-slim[service-client]`	The same client, when you want to choose the extras yourself
`docling`	You also want to convert documents locally, on your own machine

To keep the command out of your project environment, install it as a tool: uv tool install docling-client or pipx install docling-client.

Set your credentials

The command reads the Service URL and API key from, in order of precedence:

the flags --service-url and --api-key
the environment variables DOCLING_SERVICE_URL and DOCLING_SERVICE_API_KEY
a .env file in the current working directory

The simplest setup is a .env file in the folder you work from:

.env

DOCLING_SERVICE_URL=https://your-service-url
DOCLING_SERVICE_API_KEY=your-api-key

Add .env to your .gitignore. Never commit an API key.

Convert documents

# One local file, Markdown written to ./report.md
docling convert-remote report.pdf

# A URL, written to ./out
docling convert-remote --output ./out https://arxiv.org/pdf/2408.09869

# Several sources at once
docling convert-remote report.pdf minutes.docx handbook.epub

# A whole folder (walked recursively), only PDF and DOCX files
docling convert-remote --from pdf --from docx --output ./out ./inbox

Each source produces one file per requested format, named after the source: report.md, report.dclx, and so on. URLs are passed to the service as they are, and are not downloaded locally first.

Markdown and DocLang together

Markdown is easy to read. DocLang keeps the full structure: sections, tables down to the cell, reading order and page positions. Ask for both in one call:

docling convert-remote --to md --to dclx --output ./out report.pdf

Open out/report.dclx in the DocLang Viewer, or query it from the terminal with dclq:

pip install dclq
dclq outline ./out/report.dclx
dclq show ./out/report.dclx '/heading[2]' --section

See Explore with DocLang for more.

Options

All options are flags on docling convert-remote. Run docling convert-remote --help for the full list.

Inputs and outputs

Flag	Effect
`--to FORMAT`	Output format. Repeat for several. `md` (default), `json`, `html`, `text`, `doclang` (DocLang XML, `.dclg.xml`), `dclx` (DocLang archive)
`--from FORMAT`	Input formats to accept, for example `pdf`, `docx`, `pptx`, `xlsx`, `html`, `epub`, `image`. Repeat for several. Filters the files found in folders. Defaults to all supported formats
`--output DIR`	Folder for the results. Default: the current folder
`--page-range 1-4`	Convert only these pages (numbering starts at 1)
`--image-export-mode MODE`	How images appear in Markdown, HTML and JSON: `placeholder`, `embedded` or `referenced`

Conversion

Flag	Effect
`--no-ocr`	Skip OCR. Use it for born-digital PDFs where the text is already embedded
`--force-ocr`	Replace any embedded text with OCR text. Use it for scans with a bad text layer
`--ocr-lang LANGS`	Comma-separated OCR languages, for example `en,de`
`--no-tables`	Skip table structure recognition. Faster, but tables become plain text

Pictures

Flag	Effect
`--enrich-picture-classes`	Classify each picture (chart, diagram, photo, logo, …). Off by default

Client behaviour

Flag	Effect
`--max-concurrency N`	How many documents are converted at the same time
`--timeout SECONDS`	How long to wait for each document. Default: 300
`--document-timeout SECONDS`	Processing time limit for each document on the service
`--abort-on-error`	Stop at the first failed document
`--watcher polling`	Track progress by polling the status endpoint. The default, `websocket`, falls back to polling automatically
`-v`, `-vv`	Info or debug logging

A full example

Convert a born-digital PDF to Markdown and DocLang, classify its pictures and embed them in the Markdown:

docling convert-remote \
  --to md --to dclx \
  --no-ocr \
  --enrich-picture-classes \
  --image-export-mode embedded \
  --output ./out \
  report.pdf

Exit codes

Code	Meaning
`0`	All documents converted
`1`	Runtime or connection failure: the service is unreachable, or a conversion failed
`2`	Configuration error: no Service URL from the flag, the environment or `.env`

Use them in scripts, for example docling convert-remote ./inbox || echo "conversion failed".

When to use something else

You want to	Use
Convert from Python code	the Python SDK
Convert thousands of files, or read from and write to cloud storage	Batch Conversion with connectors
Chunk documents for retrieval	Chunking
Let an AI assistant convert documents for you	Agent Skills or MCP

Command Line

On this page