Environment Variables

all2md supports configuration through environment variables, providing a convenient way to set defaults for CLI commands, control security settings, and configure application behavior. This reference documents all available environment variables and their usage.

Overview

Environment variables in all2md follow these patterns:

  1. Global Security Controls: ALL2MD_DISABLE_NETWORK

  2. MCP Server Configuration: ALL2MD_MCP_*

  3. Configuration File: ALL2MD_CONFIG

  4. CLI Option Defaults: ALL2MD_<OPTION_NAME> (any CLI flag)

Environment variables are particularly useful for:

  • Setting security defaults in production

  • Configuring Docker containers

  • Managing CI/CD pipelines

  • Avoiding repetitive CLI flags

Security Variables

ALL2MD_DISABLE_NETWORK

Purpose: Globally disable network access to prevent SSRF attacks and unauthorized data fetching.

Type: Boolean

Default: false (network enabled by default)

Valid Values: true, 1, yes, on (case-insensitive) enable the restriction

Scope: Global - affects all document conversions

Description:

When enabled, blocks all network requests for fetching external resources (primarily affects HTML documents with remote images). This is the strongest defense against Server-Side Request Forgery (SSRF) attacks.

Impact:

  • HTML: Cannot fetch external images via <img src="http://...">

  • MHTML: Cannot fetch external resources

  • PDF/DOCX/PPTX: No impact (embedded images still work)

  • Other formats: No impact

Examples:

# Production: Disable network globally
export ALL2MD_DISABLE_NETWORK=true
all2md webpage.html

# Docker deployment
docker run -e ALL2MD_DISABLE_NETWORK=1 \
  -v /docs:/docs \
  all2md-image all2md /docs/file.html

# Python: Set before importing all2md
import os
os.environ['ALL2MD_DISABLE_NETWORK'] = '1'

from all2md import to_markdown
markdown = to_markdown('webpage.html')  # Network blocked

See Also:

  • Security - Network security documentation

  • NetworkFetchOptions.allow_remote_fetch - Per-call network control

MCP Server Variables

ALL2MD_MCP_ENABLE_TO_MD

Purpose: Enable/disable the read_document_as_markdown tool in MCP server.

Type: Boolean

Default: true

Valid Values: true, false, 1, 0, yes, no

Example:

# Disable markdown conversion (unusual)
export ALL2MD_MCP_ENABLE_TO_MD=false
all2md-mcp

ALL2MD_MCP_ENABLE_FROM_MD

Purpose: Enable/disable the save_document_from_markdown tool in MCP server.

Type: Boolean

Default: false (disabled for security - prevents arbitrary file writes)

Valid Values: true, false, 1, 0, yes, no

Example:

# Enable rendering (allows LLM to write files)
export ALL2MD_MCP_ENABLE_FROM_MD=true
all2md-mcp

ALL2MD_MCP_ALLOWED_READ_DIRS

Purpose: Semicolon-separated list of directories the MCP server can read from.

Type: String (semicolon-separated paths)

Default: Current working directory

Example:

# Allow reading from multiple directories
export ALL2MD_MCP_ALLOWED_READ_DIRS="/home/user/documents;/var/app/uploads"
all2md-mcp

# Windows paths
set ALL2MD_MCP_ALLOWED_READ_DIRS=C:\Users\User\Documents;D:\Data

ALL2MD_MCP_ADDITIONAL_READ_DIRS

Purpose: Extra read-only directories appended to the MCP read allowlist.

Type: String (semicolon-separated paths)

Default: (none)

Description:

Folders listed here are added to the read allowlist only — never the write allowlist — so the server can read from them but never write to them. Use it to grant read access to reference material alongside a writable workspace, without widening where the server may write.

Example:

# Writable workspace plus read-only reference folders
export ALL2MD_MCP_ALLOWED_READ_DIRS="/home/user/workspace"
export ALL2MD_MCP_ALLOWED_WRITE_DIRS="/home/user/workspace"
export ALL2MD_MCP_ADDITIONAL_READ_DIRS="/home/user/reference;/var/shared/docs"
all2md-mcp

ALL2MD_MCP_ALLOWED_WRITE_DIRS

Purpose: Semicolon-separated list of directories the MCP server can write to.

Type: String (semicolon-separated paths)

Default: Current working directory

Example:

# Restrict writes to output directory only
export ALL2MD_MCP_ALLOWED_WRITE_DIRS="/var/app/output"
all2md-mcp --enable-from-md

ALL2MD_MCP_ENABLE_DOC_EDIT

Purpose: Enable/disable the edit_document tool in MCP server.

Type: Boolean

Default: false (disabled for security - prevents document manipulation)

Valid Values: true, false, 1, 0, yes, no

Description:

When enabled, allows LLMs to edit documents by applying AST transformations. This is disabled by default because it allows modification of document content.

Example:

# Enable document editing (allows LLM to modify documents)
export ALL2MD_MCP_ENABLE_DOC_EDIT=true
all2md-mcp

ALL2MD_MCP_ENABLE_DIFF

Purpose: Enable/disable the diff_documents tool in MCP server.

Type: Boolean

Default: true (read-only; enabled by default)

Valid Values: true, false, 1, 0, yes, no

Description:

When enabled, allows LLMs to compare two documents and receive a unified or JSON diff. Read-only, so enabled by default.

Example:

# Disable document diffing
export ALL2MD_MCP_ENABLE_DIFF=false
all2md-mcp

ALL2MD_MCP_ENABLE_OUTLINE

Purpose: Enable/disable the get_document_outline tool in MCP server.

Type: Boolean

Default: true (read-only; enabled by default)

Valid Values: true, false, 1, 0, yes, no

Description:

When enabled, allows LLMs to retrieve a document’s heading structure for navigation. Read-only, so enabled by default.

Example:

# Disable document outlines
export ALL2MD_MCP_ENABLE_OUTLINE=false
all2md-mcp

ALL2MD_MCP_ENABLE_LIST_FILES

Purpose: Enable/disable the list_workspace_files tool in MCP server.

Type: Boolean

Default: true (read-only; enabled by default)

Valid Values: true, false, 1, 0, yes, no

Description:

When enabled, allows LLMs to list the files the server is allowed to read (path and size, with optional glob and subdirectory scoping) so they can orient themselves before reading or editing. Read-only, so enabled by default.

Example:

# Disable workspace file listing
export ALL2MD_MCP_ENABLE_LIST_FILES=false
all2md-mcp

ALL2MD_MCP_SEARCH_INDEX_DIR

Purpose: Directory used to persist and reuse the search_documents keyword index.

Type: String (directory path)

Default: (none — a fresh index is built in memory on every call)

Description:

When set, the keyword (BM25) index is saved to this directory and reused on subsequent searches, avoiding a rebuild each call. The directory must be within the write allowlist. Grep mode is always stateless and ignores this setting.

Example:

# Persist the keyword index between calls
export ALL2MD_MCP_SEARCH_INDEX_DIR="/workspace/.all2md-index"
all2md-mcp

ALL2MD_MCP_INCLUDE_IMAGES

Purpose: Control whether images are included in markdown output for vision-enabled LLMs.

Type: Boolean

Default: false

Valid Values: true, false, 1, 0, yes, no

Description:

Controls image handling in MCP server output:

  • true: Images embedded as base64 (vision-enabled LLMs can see them)

  • false: Images replaced with alt text only (faster, text-only LLMs)

Note: With ALL2MD_DISABLE_NETWORK=true (default), only works for embedded images (PDF, DOCX, PPTX), not for external HTML images that require fetching.

Example:

# Enable images for vision-enabled LLMs
export ALL2MD_MCP_INCLUDE_IMAGES=true
all2md-mcp

ALL2MD_MCP_FLAVOR

Purpose: Set the markdown flavor/dialect used by MCP server.

Type: String

Default: gfm

Valid Values: gfm, commonmark, multimarkdown, pandoc, kramdown, markdown_plus

Description:

Controls the markdown syntax flavor used for conversion. Different flavors have different syntax rules for tables, footnotes, and other elements.

Example:

# Use CommonMark flavor
export ALL2MD_MCP_FLAVOR=commonmark
all2md-mcp

ALL2MD_MCP_LOG_LEVEL

Purpose: Logging level for MCP server.

Type: String

Default: INFO

Valid Values: DEBUG, INFO, WARNING, ERROR, CRITICAL

Example:

# Enable debug logging
export ALL2MD_MCP_LOG_LEVEL=DEBUG
all2md-mcp

Configuration File

See also

Configuration Files

Complete guide to configuration files, including auto-discovery behavior, supported formats (TOML, YAML, JSON, pyproject.toml), and configuration priority.

ALL2MD_CONFIG

Purpose: Specify path to configuration file (JSON or TOML format).

Type: String (file path)

Default: None (auto-discovery is used if not set)

Description:

Points to a configuration file containing conversion options. Useful for:

  • Docker/Kubernetes ConfigMaps

  • CI/CD pipelines

  • Avoiding long command lines

  • Sharing configurations across projects

Supports both JSON and TOML formats. TOML is preferred for human editing as it supports comments.

Examples:

TOML Configuration:

# .all2md.toml
attachment_mode = "skip"

[pdf]
pages = [1, 2, 3]
detect_columns = false

[html]
strip_dangerous_elements = true

[html.network]
allow_remote_fetch = false

# Use file path
export ALL2MD_CONFIG=/etc/all2md/config.toml
all2md document.pdf

JSON Configuration:

# config.json
{
  "attachment_mode": "base64",
  "markdown": {
    "flavor": "gfm",
    "emphasis_symbol": "*"
  }
}

# Use file path
export ALL2MD_CONFIG=/etc/all2md/config.json
all2md document.pdf

Docker Usage:

# docker-compose.yml
services:
  converter:
    image: all2md:latest
    volumes:
      - ./config.toml:/etc/all2md/config.toml
    environment:
      ALL2MD_CONFIG: /etc/all2md/config.toml

Conversion Cache

The opt-in on-disk conversion cache (--cache on grep, search, chunk, view, report, roundtrip and optimize) is also controllable from the environment. See Conversion Cache for what it does.

ALL2MD_CACHE

Purpose: Enable the conversion cache without passing --cache on every command.

Type: Boolean

Default: false (cache disabled)

Valid Values: 1, true, yes, on (case-insensitive) enable it.

Example:

export ALL2MD_CACHE=1
all2md optimize scanned.pdf        # cache used without --cache

ALL2MD_CACHE_DIR

Purpose: Directory for the on-disk conversion cache.

Type: String (directory path)

Default: A per-OS user cache directory. Overridden by --cache-dir when both are set.

Example:

export ALL2MD_CACHE_DIR=/var/cache/all2md
all2md report inbox/*.docx --cache

CLI Option Environment Variables

Pattern: ALL2MD_<OPTION_NAME>

Purpose: Set default values for any CLI option.

Pattern: ALL2MD_ + uppercase option name with dashes/dots replaced by underscores

Scope: Affects CLI commands only (not programmatic API)

Examples:

Common CLI Options:

Environment Variable

CLI Flag

Example Value

ALL2MD_ATTACHMENT_MODE

--attachment-mode

skip

ALL2MD_ATTACHMENT_OUTPUT_DIR

--attachment-output-dir

./images

ALL2MD_RICH

--rich

true

ALL2MD_FORCE_RICH

--force-rich

true

ALL2MD_OUTPUT_DIR

--output-dir

./converted

ALL2MD_REMOTE_INPUT_ENABLED

--remote-input-enabled

true

ALL2MD_REMOTE_INPUT_ALLOWED_HOSTS

--remote-input-allowed-hosts

docs.example.com,cdn.example.com

ALL2MD_REMOTE_INPUT_ALLOW_HTTP

--remote-input-allow-http

true

ALL2MD_REMOTE_INPUT_TIMEOUT

--remote-input-timeout

15

ALL2MD_REMOTE_INPUT_MAX_SIZE_BYTES

--remote-input-max-size-bytes

10485760

ALL2MD_REMOTE_INPUT_USER_AGENT

--remote-input-user-agent

MyCrawler/1.0

ALL2MD_STRICT_ARGS

--strict-args

true

ALL2MD_FORMAT

--format

pdf

ALL2MD_RICH_CODE_THEME

--rich-code-theme

dracula

ALL2MD_RICH_INLINE_CODE_THEME

--rich-inline-code-theme

material

ALL2MD_RICH_NO_WORD_WRAP

--rich-no-word-wrap

true (disables word wrapping; wrapping is on by default)

ALL2MD_RICH_HYPERLINKS

--no-rich-hyperlinks

false

ALL2MD_RICH_JUSTIFY

--rich-justify

full

Format-Specific Options:

Environment Variable

CLI Flag

Example Value

ALL2MD_PDF_PAGES

--pdf-pages

1-10

ALL2MD_PDF_DETECT_COLUMNS

--pdf-detect-columns

true

ALL2MD_HTML_STRIP_DANGEROUS_ELEMENTS

--html-strip-dangerous-elements

true

ALL2MD_MARKDOWN_FLAVOR

--markdown-flavor

gfm

ALL2MD_MARKDOWN_EMPHASIS_SYMBOL

--markdown-emphasis-symbol

_

Nested Options:

For nested options (e.g., --html-network-allow-remote-fetch), replace all separators with underscores:

# CLI: --html-network-allow-remote-fetch
export ALL2MD_HTML_NETWORK_ALLOW_REMOTE_FETCH=false

# CLI: --pdf-enable-table-fallback-detection
export ALL2MD_PDF_ENABLE_TABLE_FALLBACK_DETECTION=true

Usage Example:

# Set defaults via environment
export ALL2MD_ATTACHMENT_MODE=skip
export ALL2MD_PDF_PAGES="1-5"
export ALL2MD_RICH=true

# CLI commands use these defaults
all2md document.pdf  # Uses pages=1-5, attachment_mode=skip, rich=true

# Override specific defaults
all2md document.pdf --pdf-pages "1-10"  # Overrides env var

Type Conversion:

Environment variable values are automatically converted to appropriate types:

  • Boolean: true, false, 1, 0, yes, no, on, off

  • Integer: Numeric strings ("10")

  • String: Text values

  • Lists: Comma-separated ("1,2,3")

Remote Document Conversion Defaults

Use the remote-input environment variables to allow trusted HTTP(S) sources without repeating CLI flags:

export ALL2MD_REMOTE_INPUT_ENABLED=true
export ALL2MD_REMOTE_INPUT_ALLOWED_HOSTS="docs.example.com,cdn.example.com"
export ALL2MD_REMOTE_INPUT_TIMEOUT=15
export ALL2MD_REMOTE_INPUT_MAX_SIZE_BYTES=10485760  # 10 MiB

all2md https://docs.example.com/manual.pdf --output-dir ./manuals

Practical Examples

Production Web Server

# .env file
ALL2MD_DISABLE_NETWORK=true
ALL2MD_ATTACHMENT_MODE=skip
ALL2MD_CONFIG=/etc/all2md/production.toml

# Start server
uvicorn app:main --env-file .env

Docker Container

# Dockerfile
FROM python:3.12-slim
RUN pip install all2md[all]

# Set environment defaults
ENV ALL2MD_DISABLE_NETWORK=true \
    ALL2MD_ATTACHMENT_MODE=skip \
    ALL2MD_PDF_DETECT_COLUMNS=false

CMD ["all2md"]

# Run with custom env vars
docker run \
  -e ALL2MD_ATTACHMENT_MODE=base64 \
  -e ALL2MD_PDF_PAGES="1-10" \
  -v /docs:/docs \
  all2md-image all2md /docs/file.pdf

CI/CD Pipeline

GitHub Actions:

# .github/workflows/convert-docs.yml
name: Convert Documents
on: [push]

jobs:
  convert:
    runs-on: ubuntu-latest
    env:
      ALL2MD_DISABLE_NETWORK: "true"
      ALL2MD_ATTACHMENT_MODE: "skip"
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.12'
      - run: pip install all2md[all]
      - run: all2md docs/*.pdf --output-dir converted/

GitLab CI:

# .gitlab-ci.yml
convert-docs:
  image: python:3.12
  variables:
    ALL2MD_DISABLE_NETWORK: "true"
    ALL2MD_ATTACHMENT_MODE: "skip"
    ALL2MD_PDF_PAGES: "1-5"
  script:
    - pip install all2md[all]
    - all2md documents/*.pdf --output-dir converted/
  artifacts:
    paths:
      - converted/

MCP Server Deployment

# Production MCP server with strict security
export ALL2MD_MCP_ENABLE_TO_MD=true
export ALL2MD_MCP_ENABLE_FROM_MD=false
export ALL2MD_MCP_ENABLE_DOC_EDIT=false
export ALL2MD_MCP_ALLOWED_READ_DIRS="/var/app/uploads"
export ALL2MD_MCP_ALLOWED_WRITE_DIRS="/var/app/output"
export ALL2MD_MCP_INCLUDE_IMAGES=false
export ALL2MD_MCP_FLAVOR=gfm
export ALL2MD_DISABLE_NETWORK=true
export ALL2MD_MCP_LOG_LEVEL=WARNING

all2md-mcp

Systemd Service:

# /etc/systemd/system/all2md-mcp.service
[Unit]
Description=all2md MCP Server
After=network.target

[Service]
Type=simple
User=all2md
Environment="ALL2MD_DISABLE_NETWORK=true"
Environment="ALL2MD_MCP_ALLOWED_READ_DIRS=/var/app/uploads"
Environment="ALL2MD_MCP_ALLOWED_WRITE_DIRS=/var/app/output"
Environment="ALL2MD_MCP_INCLUDE_IMAGES=false"
Environment="ALL2MD_MCP_FLAVOR=gfm"
Environment="ALL2MD_MCP_LOG_LEVEL=INFO"
ExecStart=/usr/local/bin/all2md-mcp
Restart=always

[Install]
WantedBy=multi-user.target

Development vs Production

Development (.env.development):

# Development: Permissive settings
ALL2MD_DISABLE_NETWORK=false
ALL2MD_ATTACHMENT_MODE=save
ALL2MD_ATTACHMENT_OUTPUT_DIR=./dev-images
ALL2MD_RICH=true
ALL2MD_MCP_LOG_LEVEL=DEBUG

Production (.env.production):

# Production: Secure settings
ALL2MD_DISABLE_NETWORK=true
ALL2MD_ATTACHMENT_MODE=skip
ALL2MD_CONFIG=/etc/all2md/production-config.toml
ALL2MD_MCP_LOG_LEVEL=WARNING

Load Appropriately:

# Python application
from dotenv import load_dotenv
import os

# Load environment-specific config
env = os.getenv('ENVIRONMENT', 'development')
load_dotenv(f'.env.{env}')

from all2md import to_markdown
markdown = to_markdown('document.pdf')

Environment Variable Precedence

When multiple configuration sources are present, they are applied in this order (later sources override earlier). This is the same ordering described — highest-first — in Configuration Files:

  1. Built-in defaults, including any default supplied by a per-option ALL2MD_<OPTION> environment variable (these set the default for a flag you do not pass explicitly)

  2. Configuration file — a single file resolved as: the --config flag, else the ALL2MD_CONFIG environment variable, else an auto-discovered .all2md.toml/.all2md.json

  3. Presets (--preset and the security presets)

  4. CLI arguments (explicitly provided flags; highest precedence)

Note

ALL2MD_CONFIG points at a configuration file, whereas the per-option ALL2MD_<OPTION> variables supply individual option defaults — they are different mechanisms.

Example:

# Auto-discovered config
# .all2md.toml contains: attachment_mode = "skip"

# Environment variable
export ALL2MD_ATTACHMENT_MODE=base64

# Explicit config file
export ALL2MD_CONFIG=custom.toml  # contains: attachment_mode = "save"

# CLI flag
all2md document.pdf --attachment-mode inline

# Final value: "inline" (CLI wins over all)

Validation and Error Handling

Invalid Values

Invalid environment variable values trigger errors:

# Invalid boolean
export ALL2MD_DISABLE_NETWORK=maybe
all2md document.pdf
# Error: Invalid boolean value for ALL2MD_DISABLE_NETWORK

# Invalid choice
export ALL2MD_ATTACHMENT_MODE=invalid
all2md document.pdf
# Error: Invalid attachment_mode: must be skip, alt_text, base64, or save

Required Values

Some environment variables require specific formats:

# Invalid page range
export ALL2MD_PDF_PAGES='abc'
all2md document.pdf
# Error: Invalid page range specification: abc

Type Mismatches

Environment variables are validated against expected types:

# Expecting boolean, got string
export ALL2MD_PDF_DETECT_COLUMNS=maybe
all2md document.pdf
# Error: Cannot convert 'maybe' to boolean

Quick Reference

Most Common Variables:

# Security (production)
export ALL2MD_DISABLE_NETWORK=true

# Attachment handling
export ALL2MD_ATTACHMENT_MODE=skip

# Output configuration
export ALL2MD_RICH=true
export ALL2MD_OUTPUT_DIR=./converted

# PDF-specific
export ALL2MD_PDF_PAGES="1-10"

# HTML security
export ALL2MD_HTML_STRIP_DANGEROUS_ELEMENTS=true

# Configuration file
export ALL2MD_CONFIG=/path/to/config.toml

MCP Server:

export ALL2MD_MCP_ENABLE_TO_MD=true
export ALL2MD_MCP_ENABLE_FROM_MD=false
export ALL2MD_MCP_ENABLE_DOC_EDIT=false
export ALL2MD_MCP_ALLOWED_READ_DIRS="/path/to/docs"
export ALL2MD_MCP_ALLOWED_WRITE_DIRS="/path/to/output"
export ALL2MD_MCP_INCLUDE_IMAGES=false
export ALL2MD_MCP_FLAVOR=gfm
export ALL2MD_DISABLE_NETWORK=true
export ALL2MD_MCP_LOG_LEVEL=INFO

See Also