CLI

Reference

CLI Commands

Complete reference for all Kilometers CLI commands, environment variables, and usage examples.

Available Commands

km --version

Display version information

km -v

km version

Example:

km --version

Output:

Kilometers CLI cli-v2025.07.10.1
Build time: 2025-07-10T05:50:24Z
Go version: go1.24.4
Platform: darwin/arm64

km --help

Show help information and usage

km -h

km help

Example:

km --help

Output:

Usage:
  km <mcp-server-command> [args...]  Wrap an MCP server
  km version                         Show version information
  km update                          Update to latest version
  km help                            Show this help message

Examples:
  km npx @modelcontextprotocol/server-github
  km python -m slack_mcp_server

km init

Interactive configuration setup - guides you through setting up API key and other options

Example:

km init

Output:

🚀 Kilometers CLI Configuration Setup

This will guide you through setting up your Kilometers CLI configuration.
You can press Enter to accept default values shown in brackets.

API Key (required):

km update

Update to the latest version (currently shows placeholder message)

Example:

km update

Output:

km cli tool @ cli-v2025.07.10.1
Update functionality coming soon!

For now, download the latest version from:
  https://github.com/kilometers-ai/kilometers/releases/latest

km <mcp-server-command>

Wrap and monitor any MCP server

Example:

km npx @modelcontextprotocol/server-github

Output:

[km] Starting Kilometers CLI wrapper for: [npx @modelcontextprotocol/server-github]
[km] Started process with PID: 12345
[km] Event #1: request tools/call (156 bytes)

Environment Variables

KILOMETERS_API_URL

API endpoint URL

Default:http://localhost:5194

Example:https://api.kilometers.ai

KILOMETERS_API_KEY

Required

API authentication key

Default:(none)

Example:km_1234567890abcdef

KILOMETERS_CUSTOMER_ID

Customer identifier

Default:default

Example:company-123

KM_DEBUG

Enable debug logging

Default:false

Example:true

KM_BATCH_SIZE

Events per API batch

Default:10

Example:20

KM_ENABLE_RISK_DETECTION

Enable client-side risk analysis

Default:false

Example:true

KM_METHOD_WHITELIST

Comma-separated list of methods to capture

Default:(none)

Example:tools/call,resources/read

KM_PAYLOAD_SIZE_LIMIT

Maximum payload size in bytes (0 = no limit)

Default:0

Example:10240

KM_HIGH_RISK_ONLY

Only capture high-risk events

Default:false

Example:true

KM_EXCLUDE_PING

Exclude ping messages from monitoring

Default:true

Example:false

Usage Examples

Basic MCP Server Monitoring

Monitor a GitHub MCP server

km npx @modelcontextprotocol/server-github

Debug Mode

Enable verbose logging to see what's being captured

KM_DEBUG=true km npx @modelcontextprotocol/server-github

Security-Focused Monitoring

Only capture high-risk events with risk detection enabled

KM_ENABLE_RISK_DETECTION=true KM_HIGH_RISK_ONLY=true km your-mcp-server

Method-Specific Monitoring

Only monitor specific MCP methods

KM_METHOD_WHITELIST="tools/call,resources/read" km your-mcp-server

Bandwidth-Conscious Setup

Limit payload sizes and exclude ping messages

KM_PAYLOAD_SIZE_LIMIT=5120 KM_EXCLUDE_PING=true km your-mcp-server

Tips and Best Practices

Environment Variables

Add your environment variables to your shell profile (~/.bashrc, ~/.zshrc) to persist them across sessions.

Security Best Practices

Enable risk detection and use method whitelisting for production environments to minimize security risks.

Performance Optimization

Use payload size limits and exclude ping messages to reduce bandwidth usage and improve performance.

Next Steps

Environment Variables

Learn about all available environment variables for configuration.

Environment Guide

Event Filtering

Configure advanced filtering to capture only the events you need.

Filtering Guide