Environment Configuration

To use ContextMD, you must provide an OpenAI API key. This key is used by the AI-powered refinement engine to process scraped HTML and convert it into high-density, agent-ready Markdown.

Required Environment Variables

The primary configuration variable is OPENAI_API_KEY. You can set this in your shell or via a local configuration file.

Configuration Methods

You can provide the API key using one of the following three methods, listed in order of precedence.

1. Command-Line Flag (Highest Priority)

Pass the key directly when running the command using the -k or --key flag. This is useful for one-off runs or CI/CD pipelines.

npx contextmd https://docs.example.com --key sk-proj-your-api-key

2. Local `.env` File

Create a .env file in the directory where you are running the command. ContextMD automatically detects and loads variables from this file.

File: .env

OPENAI_API_KEY=sk-proj-your-api-key

3. Shell Environment Variable

Export the key in your terminal session. This is the recommended approach for local development.

macOS / Linux:

export OPENAI_API_KEY="sk-proj-your-api-key"

Windows (PowerShell):

$env:OPENAI_API_KEY="sk-proj-your-api-key"

Precedence Rules

If multiple methods are used simultaneously, ContextMD resolves the key in the following order:

CLI Flag (--key)
Shell Environment Variable
.env file (loaded via dotenv)

Security Best Practices

Never commit your .env file: Ensure .env is added to your .gitignore to prevent leaking API keys to public repositories.
Restricted Keys: If possible, use an OpenAI Project API Key with permissions limited to the specific project you are documenting.
Usage Limits: Monitor your OpenAI dashboard. While the default model used (gpt-4o-mini) is cost-effective, crawling very large documentation sites (over 1,000 pages) can incur noticeable costs.

Environment Configuration