Reference

Complete configuration guide

Environment Variables Reference

Complete reference for all Kilometers CLI environment variables with descriptions, defaults, and usage examples.

Configuration Priority

Environment variables take precedence over configuration files. The CLI checks for environment variables first, then falls back to config file values, and finally uses built-in defaults.

Environment Variables (highest priority)
Configuration file ~/.config/kilometers/config.json
Built-in defaults (lowest priority)

Core Configuration

Essential settings for API connection and basic operation

KILOMETERS_API_URL

Default: http://localhost:5194

API endpoint URL for the Kilometers service

Examples:

KILOMETERS_API_URL="https://api.kilometers.ai"

Production API endpoint

KILOMETERS_API_URL="http://localhost:5194"

Local development server

KILOMETERS_API_URL="https://staging-api.kilometers.ai"

Staging environment

KILOMETERS_API_KEY

Required

Default: (none)

API authentication key for accessing the service

Examples:

KILOMETERS_API_KEY="km_1234567890abcdef"

Production API key

KILOMETERS_API_KEY="km_dev_abcdef1234567890"

Development API key

KILOMETERS_CUSTOMER_ID

Default: default

Customer identifier for multi-tenant environments

Examples:

KILOMETERS_CUSTOMER_ID="default"

Default customer ID

KILOMETERS_CUSTOMER_ID="company-123"

Custom customer identifier

KILOMETERS_CUSTOMER_ID="team-frontend"

Team-specific identifier

KM_BATCH_SIZE

Default: 10

Number of events to batch before sending to API

Examples:

KM_BATCH_SIZE="5"

Smaller batches for real-time monitoring

KM_BATCH_SIZE="20"

Larger batches for high-volume environments

KM_BATCH_SIZE="1"

Send events immediately (no batching)

Debug & Logging

Control logging and debug output

KM_DEBUG

Default: false

Enable detailed debug logging

Examples:

KM_DEBUG="true"

Enable debug output

KM_DEBUG="false"

Standard logging only

Security & Risk Detection

Configure client-side security analysis and risk detection

KM_ENABLE_RISK_DETECTION

Default: false

Enable client-side risk analysis of events

Examples:

KM_ENABLE_RISK_DETECTION="true"

Enable risk scoring

KM_ENABLE_RISK_DETECTION="false"

Disable risk analysis

KM_HIGH_RISK_ONLY

Default: false

Only capture high-risk events (75+ score)

Examples:

KM_HIGH_RISK_ONLY="true"

Security-focused monitoring

KM_HIGH_RISK_ONLY="false"

Capture all risk levels

Event Filtering

Control which events are captured and monitored

KM_METHOD_WHITELIST

Default: (none)

Comma-separated list of MCP methods to capture

Examples:

KM_METHOD_WHITELIST="tools/call"

Only monitor tool executions

KM_METHOD_WHITELIST="resources/read,resources/write"

File operations only

KM_METHOD_WHITELIST="tools/*"

All tool-related methods

KM_METHOD_WHITELIST="resources/*,prompts/get"

Resources and prompts

KM_PAYLOAD_SIZE_LIMIT

Default: 0

Maximum payload size in bytes (0 = no limit)

Examples:

KM_PAYLOAD_SIZE_LIMIT="1024"

1KB limit for low bandwidth

KM_PAYLOAD_SIZE_LIMIT="10240"

10KB limit for normal usage

KM_PAYLOAD_SIZE_LIMIT="0"

No size restriction

KM_EXCLUDE_PING

Default: true

Exclude ping messages from monitoring

Examples:

KM_EXCLUDE_PING="true"

Skip ping messages (recommended)

KM_EXCLUDE_PING="false"

Include ping messages

Configuration Presets

Pre-configured environment variable sets for common use cases:

Development Mode

Full visibility with debug logging

ENVIRONMENT VARIABLES

KILOMETERS_API_URL="http://localhost:5194"
KILOMETERS_API_KEY="your-dev-key"
KM_DEBUG=true
KM_EXCLUDE_PING=true

Production Security

High-risk monitoring only

ENVIRONMENT VARIABLES

KILOMETERS_API_URL="https://api.kilometers.ai"
KILOMETERS_API_KEY="your-prod-key"
KM_ENABLE_RISK_DETECTION=true
KM_HIGH_RISK_ONLY=true
KM_PAYLOAD_SIZE_LIMIT=10240

Bandwidth Optimized

Minimal data transfer

ENVIRONMENT VARIABLES

KILOMETERS_API_URL="https://api.kilometers.ai"
KILOMETERS_API_KEY="your-key"
KM_METHOD_WHITELIST="tools/call,resources/write"
KM_PAYLOAD_SIZE_LIMIT=5120
KM_BATCH_SIZE=20
KM_EXCLUDE_PING=true

Setting Environment Variables

🐧Linux/macOS

Temporary (current session):

export KILOMETERS_API_KEY="your-key"

Persistent (add to ~/.bashrc or ~/.zshrc):

echo 'export KILOMETERS_API_KEY="your-key"' >> ~/.bashrc

🪟Windows

PowerShell (temporary):

$env:KILOMETERS_API_KEY="your-key"

Command Prompt (temporary):

set KILOMETERS_API_KEY=your-key

Validating Configuration

Use these commands to verify your environment variables are set correctly:

Check all KM variables:

env | grep ^KM

Check Kilometers variables:

env | grep ^KILOMETERS

Test CLI with debug:

KM_DEBUG=true km --version

Event Filtering Quick Start Guide