> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/microsoft/markitdown/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Usage

> Complete guide to using MarkItDown from the command line

MarkItDown provides a powerful command-line interface for converting various file formats to Markdown.

## Basic Usage

Convert a file to Markdown and output to stdout:

```bash theme={null}
markitdown example.pdf
```

## Input Methods

MarkItDown supports multiple ways to provide input:

<CodeGroup>
  ```bash Direct file path theme={null}
  markitdown example.pdf
  ```

  ```bash Pipe from cat theme={null}
  cat example.pdf | markitdown
  ```

  ```bash Input redirection theme={null}
  markitdown < example.pdf
  ```
</CodeGroup>

<Note>
  When reading from stdin (pipe or redirection), you may need to provide hints about the file type using `--extension` or `--mime-type` flags.
</Note>

## Output Options

Control where the Markdown output is written:

<CodeGroup>
  ```bash Output to file with -o flag theme={null}
  markitdown example.pdf -o example.md
  ```

  ```bash Output redirection theme={null}
  markitdown example.pdf > example.md
  ```

  ```bash Output to stdout (default) theme={null}
  markitdown example.pdf
  ```
</CodeGroup>

## Command-Line Flags

### Version Information

```bash theme={null}
markitdown --version
markitdown -v
```

Displays the version number and exits.

### File Type Hints

When reading from stdin or when the file type cannot be automatically detected:

```bash theme={null}
markitdown -x .pdf < document
markitdown --extension pdf < document
```

Provide a hint about the file extension. The leading dot is optional.

```bash theme={null}
markitdown -m application/pdf < document
markitdown --mime-type application/pdf < document
```

Provide a hint about the MIME type.

```bash theme={null}
markitdown -c UTF-8 < document
markitdown --charset UTF-8 < document
```

Provide a hint about the character encoding.

### Azure Document Intelligence

Use Azure Document Intelligence for cloud-based conversion:

```bash theme={null}
markitdown -d -e https://YOUR_ENDPOINT.cognitiveservices.azure.com/ example.pdf
markitdown --use-docintel --endpoint https://YOUR_ENDPOINT.cognitiveservices.azure.com/ example.pdf
```

<Warning>
  Document Intelligence requires:

  * A valid Azure endpoint URL (required)
  * Authentication via `AZURE_API_KEY` environment variable or Azure credentials
  * A file path (stdin is not supported with Document Intelligence)
</Warning>

### Plugin Support

Enable third-party plugins:

```bash theme={null}
markitdown -p example.rtf
markitdown --use-plugins example.rtf
```

List installed plugins:

```bash theme={null}
markitdown --list-plugins
```

Output shows:

```
Installed MarkItDown 3rd-party Plugins:

  * sample_plugin    	(package: markitdown_sample_plugin)

Use the -p (or --use-plugins) option to enable 3rd-party plugins.
```

<Tip>
  Find plugins by searching for the hashtag `#markitdown-plugin` on GitHub.
</Tip>

### Data URI Handling

By default, data URIs (like base64-encoded images) are truncated in the output:

```bash theme={null}
markitdown --keep-data-uris example.html
```

Keeps full data URIs in the output, which can significantly increase file size.

## Common Patterns

### Batch Conversion

Convert multiple files:

```bash theme={null}
for file in *.pdf; do
    markitdown "$file" -o "${file%.pdf}.md"
done
```

### Piping with Processing

Combine with other tools:

```bash theme={null}
# Download and convert
curl https://example.com/document.pdf | markitdown -x .pdf > output.md

# Convert and count words
markitdown document.docx | wc -w

# Convert and search
markitdown report.pdf | grep "quarterly results"
```

### Using with stdin Hints

When the file type cannot be inferred from context:

```bash theme={null}
# Provide extension hint
cat mystery_file | markitdown -x .xlsx -o output.md

# Provide MIME type hint
echo "data" | markitdown -m text/plain

# Provide charset hint for non-UTF-8 files
markitdown -c ISO-8859-1 -x .txt < legacy_file
```

## Exit Codes

* **0**: Successful conversion
* **1**: Error occurred (file not found, conversion failed, invalid arguments, etc.)

## Examples by File Type

<Steps>
  <Step title="PDF Documents">
    ```bash theme={null}
    markitdown document.pdf -o document.md
    ```
  </Step>

  <Step title="Word Documents">
    ```bash theme={null}
    markitdown report.docx -o report.md
    ```
  </Step>

  <Step title="Excel Spreadsheets">
    ```bash theme={null}
    markitdown data.xlsx -o data.md
    ```
  </Step>

  <Step title="PowerPoint Presentations">
    ```bash theme={null}
    markitdown slides.pptx -o slides.md
    ```
  </Step>

  <Step title="Images with Metadata">
    ```bash theme={null}
    markitdown photo.jpg -o photo.md
    ```
  </Step>
</Steps>

## Troubleshooting

### Encoding Issues

If you see garbled characters, try specifying the charset:

```bash theme={null}
markitdown -c UTF-8 file.txt
```

### File Type Not Detected

Provide explicit hints:

```bash theme={null}
markitdown -x .pdf -m application/pdf < file
```

### Missing Dependencies

If conversion fails due to missing dependencies, install the appropriate optional dependencies:

```bash theme={null}
pip install markitdown[pdf]  # For PDF support
pip install markitdown[all]  # For all formats
```

See the [Optional Dependencies](/guides/optional-dependencies) guide for details.