The intelligent MCP proxy for modern AI workflows
A high-performance Rust-based MCP (Model Context Protocol) proxy that intelligently monitors, logs, and enhances AI model interactions while providing comprehensive telemetry and risk analysis.
🚀 Quick Start • 📖 Documentation • 💬 Community • 🐛 Report Bug • ✨ Request Feature
- 🎯 Overview
- ✨ Features
- 🚀 Quick Start
- 📦 Installation
- 🔧 Configuration
- 🎮 Usage
- 🏗️ Architecture
- 💻 Development
- 🚀 Deployment
- 🔍 Troubleshooting
- 🗺️ Roadmap
- 🤝 Contributing
- 🌟 Community
- 📄 License
Kilometers CLI is a sophisticated Model Context Protocol (MCP) proxy designed for developers and organizations who need intelligent monitoring, logging, and risk analysis of their AI model interactions. Built with Rust for maximum performance and reliability, it seamlessly integrates into existing AI workflows while providing enterprise-grade telemetry and security features.
- 🔍 Complete Visibility: Monitor every MCP request and response with detailed logging
- 🛡️ Risk Analysis: Intelligent filtering and risk assessment for enterprise security
- 📊 Rich Telemetry: Comprehensive analytics and usage tracking via the Kilometers.ai platform
- ⚡ High Performance: Built in Rust for minimal latency and maximum throughput
- 🔧 Zero Configuration: Works out-of-the-box with sensible defaults
- 🌐 Universal Compatibility: Works with any MCP-compliant client and server
- AI Developers building applications with Claude Desktop, VS Code extensions, or custom MCP clients
- DevOps Teams monitoring AI infrastructure and usage patterns
- Security Engineers implementing governance and risk management for AI systems
- Organizations requiring audit trails and compliance for AI model usage
|
|
|
|
Get up and running with Kilometers CLI in under 2 minutes:
# One-liner installation (recommended)
curl -fsSL https://install.kilometers.ai | sh# Set up your API key
km init# Monitor any MCP server (example: filesystem server)
km monitor -- npx -y @modelcontextprotocol/server-filesystem ~/DocumentsThat's it! 🎉 Your MCP traffic is now being monitored, logged, and analyzed.
💡 Want to see it in action?
# Terminal 1: Start the proxy
km monitor -- npx -y @modelcontextprotocol/server-filesystem ~/Documents
# Terminal 2: Connect with Claude Desktop or any MCP client
# Your requests will be logged and analyzed automaticallyCheck your logs at ~/.local/share/km/mcp_proxy.log to see the captured traffic!
Choose your preferred installation method:
# Unix/Linux/macOS
curl -fsSL https://install.kilometers.ai | sh
# Windows (PowerShell)
iwr https://install.kilometers.ai/windows | iex🔍 What does the installer do?
The installation script:
- ✅ Detects your operating system and architecture
- ✅ Downloads the latest release binary
- ✅ Installs to
/usr/local/bin(Unix) orProgram Files(Windows) - ✅ Sets up shell completions
- ✅ Verifies installation with
km --version
| Cargo | cargo install km |
| Homebrew | brew install kilometers-ai/tap/km |
| Scoop (Windows) | scoop install km |
| Arch Linux | yay -S km-bin |
# Run directly
docker run --rm -it kilometers/km:latest init
# Use with volume mounts for persistent config
docker run --rm -v ~/.config/km:/root/.config/km kilometers/km:latest monitor -- <your-command>Download platform-specific binaries from our releases page:
| Platform | Architecture | Download |
|---|---|---|
| Linux | x86_64 | km-linux-x86_64 |
| Linux | ARM64 | km-linux-arm64 |
| macOS | x86_64 | km-macos-x86_64 |
| macOS | ARM64 (M1/M2) | km-macos-arm64 |
| Windows | x86_64 | km-windows-x86_64.exe |
# Prerequisites: Rust 1.70+, Git
git clone https://github.com/kilometers-ai/kilometers-cli.git
cd kilometers-cli
cargo build --release
cp target/release/km /usr/local/bin/# Check version and basic functionality
km --version
km --help
# Test with a simple command
km init --helpKilometers CLI offers flexible configuration options to fit any workflow:
Get your API key from kilometers.ai and configure it:
# Interactive setup (recommended)
km init
# Or set via environment variable
export KM_API_KEY="km_live_your_api_key_here"Security Note: Your API key and authentication tokens are securely stored in your operating system's native credential manager (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux).
Configuration is loaded in this order of precedence:
- 🔴 Environment Variables (highest priority)
- 🟡 Configuration File
- 🟢 Default Values (lowest priority)
# Required
export KM_API_KEY="km_live_your_api_key_here"
# Optional
export KM_API_URL="https://api.kilometers.ai" # API endpoint
export KM_DEFAULT_TIER="enterprise" # User tier override
export KM_LOG_LEVEL="info" # Logging verbosity
export KM_CONFIG_DIR="$HOME/.config/km" # Config directory
export KM_DATA_DIR="$HOME/.local/share/km" # Data directoryLocation: ~/.config/km/config.json (or %APPDATA%\km\config.json on Windows)
Note: The configuration file stores settings only. API keys and authentication tokens are stored securely in your OS keyring.
{
"api_url": "https://api.kilometers.ai",
"default_tier": "enterprise",
"log_level": "info",
"telemetry": {
"enabled": true,
"batch_size": 100,
"flush_interval": 30
},
"risk_analysis": {
"enabled": true,
"threshold": 0.8,
"block_high_risk": true
},
"proxy": {
"timeout": 30,
"max_retries": 3,
"buffer_size": 8192
}
}For local development, create a .env file in your project root:
# Copy the example
cp .env.example .env
# Edit with your values
KM_API_KEY=km_live_your_api_key_here
KM_API_URL=https://api.kilometers.ai
KM_DEFAULT_TIER=enterprise| OS | Config Directory | Data Directory | Credential Storage |
|---|---|---|---|
| Linux | ~/.config/km/ |
~/.local/share/km/ |
Secret Service (D-Bus) |
| macOS | ~/.config/km/ |
~/.local/share/km/ |
Keychain |
| Windows | %APPDATA%\km\ |
%APPDATA%\km\ |
Credential Manager |
Kilometers CLI adapts its behavior based on your subscription tier:
| Feature | Free Tier | Paid Tier |
|---|---|---|
| Local Logging | ✅ | ✅ |
| Telemetry | ❌ | ✅ |
| Risk Analysis | ❌ | ✅ |
| Command Transformation | ❌ | ✅ |
| Priority Support | ❌ | ✅ |
Set up or update your Kilometers.ai API key:
# Interactive setup
km init
# Non-interactive with validation
km init --api-key "km_live_your_key" --validate
# Update existing configuration
km init --updateWhen an API key is not provided, km init uses a device code flow so you can authenticate via the dashboard:
Open to sign in: https://app.kilometers.ai/device?user_code=ABCD-1234
Or visit https://app.kilometers.ai/device and enter code: ABCD-1234
Steps:
- Open the printed link (or visit
/device) in your browser - Approve the device request (login required; redirects to
/loginif needed) - Return to the terminal once you see "Device linked. You can return to the terminal."
The CLI polls in the background until the approval completes, then securely stores tokens in your OS keyring.
- Set
CI=1to skip OS keyring access and force non-interactive behavior - If device approval is unavailable in CI, use an API key fallback:
km init --api-key "$KM_API_KEY" --api-url "$KM_API_URL"Environment variables that affect km init:
KM_API_URL– API base URL (e.g., https://api.kilometers.ai)KM_API_KEY– Use when bypassing device code flowCI– Set to1in CI/headless environments
The heart of Kilometers CLI - monitor and proxy MCP traffic:
# Basic usage
km monitor -- <command> [args...]
# Examples
km monitor -- npx -y @modelcontextprotocol/server-filesystem ~/Documents
km monitor -- python mcp-server.py --port 8080
km monitor -- ./my-custom-mcp-server --config server.jsonAdvanced Options:
# Enable verbose logging
km monitor --verbose -- <command>
# Custom session ID for tracking
km monitor --session-id "my-session-123" -- <command>
# Override API settings
km monitor --api-url "https://dev-api.kilometers.ai" -- <command>Clean up local log files:
# Clear all logs
km clear-logs
# Clear logs older than 7 days
km clear-logs --older-than 7d
# Interactive confirmation
km clear-logs --interactive# Monitor Claude Desktop's MCP server connections
km monitor -- npx -y @modelcontextprotocol/server-filesystem ~/Projects# Monitor your custom MCP server during development
km monitor --verbose -- python my_mcp_server.py --debug
# In another terminal, check the logs
tail -f ~/.local/share/km/mcp_proxy.log | jq '.'# Set up environment
export KM_API_KEY="$KILOMETERS_API_KEY"
# Run tests with monitoring
km monitor -- pytest tests/ --mcp-endpoint localhost:8080# Terminal 1: Start first proxy
km monitor --session-id "proxy-1" -- server-a.py --port 8001
# Terminal 2: Start second proxy (chained)
km monitor --session-id "proxy-2" -- server-b.py --upstream localhost:8001When you run km monitor, you'll see:
🛰️ Kilometers CLI v0.2.0
📡 Initializing proxy...
🔑 Authenticating with Kilometers.ai...
✅ Authentication successful (tier: enterprise)
🚀 Starting MCP server: npx -y @modelcontextprotocol/server-filesystem ~/Documents
📝 Logging to: ~/.local/share/km/mcp_proxy.log
🔍 Session ID: 550e8400-e29b-41d4-a716-446655440000
Proxy is running. Press Ctrl+C to stop.
📈 Statistics:
Requests: 42 Responses: 41 Errors: 1
Avg Latency: 23ms Data: 1.2MB transferred
[14:30:15] DEBUG Request: {"jsonrpc":"2.0","method":"initialize","id":1}
[14:30:15] DEBUG Response: {"jsonrpc":"2.0","result":{"capabilities":{...}},"id":1}Kilometers CLI is built with a modular, layered architecture optimized for performance and maintainability:
graph TB
Client[MCP Client] --> Proxy[km proxy]
Proxy --> Server[MCP Server]
Proxy --> Logger[Local Logger]
Proxy --> Telemetry[Telemetry Service]
Proxy --> RiskAnalysis[Risk Analysis]
Telemetry --> API[Kilometers.ai API]
RiskAnalysis --> API
subgraph "Filter Pipeline"
Logger
Telemetry
RiskAnalysis
end
subgraph "Storage"
LocalLogs[mcp_proxy.log]
Config[config.json]
Keyring[OS Keyring - JWT Tokens]
end
Logger --> LocalLogs
Proxy --> Config
API --> Keyring
┌─────────────────────────────────────────────┐
│ CLI │ ← clap-based command interface
├─────────────────────────────────────────────┤
│ Application │ ← Commands, Services, Business Logic
├─────────────────────────────────────────────┤
│ Domain │ ← Core Types, Auth, Proxy Models
├─────────────────────────────────────────────┤
│ Infrastructure │ ← HTTP, File I/O, External APIs
└─────────────────────────────────────────────┘
- MCP Client sends JSON-RPC request via stdin
- km proxy receives and parses the request
- Filter Pipeline processes the request:
- Local Logger writes to
mcp_proxy.log - Telemetry Filter sends usage data (paid users only)
- Risk Analysis Filter evaluates and potentially blocks/transforms (paid users only)
- Local Logger writes to
- Process Manager forwards request to target MCP server
- MCP Server processes and responds
- Filter Pipeline processes the response (logging, telemetry)
- km proxy forwards response back to client via stdout
kilometers-cli/
├── 📁 src/
│ ├── 📄 main.rs # CLI entry point & argument parsing
│ ├── 📄 lib.rs # Library exports
│ ├── 📄 cli.rs # Command-line interface structures
│ ├── 📄 config.rs # Configuration management
│ ├── 📄 proxy.rs # Core proxy logic
│ ├── 📄 auth.rs # JWT authentication & API key exchange
│ ├── 📄 token_cache.rs # JWT token caching & expiration
│ └── 📁 filters/ # Filter pipeline system
│ ├── 📄 mod.rs # Filter trait & pipeline
│ ├── 📄 local_logger.rs # Local file logging
│ ├── 📄 event_sender.rs # Telemetry to API
│ └── 📄 risk_analysis.rs # Risk assessment & filtering
├── 📁 tests/ # Integration & unit tests
├── 📁 scripts/ # Installation & build scripts
│ ├── 📄 install.sh # Unix installation
│ ├── 📄 install.ps1 # Windows installation
│ ├── 📄 version.sh # Version management
│ └── 📁 test/ # Test automation scripts
└── 📁 .github/ # CI/CD & GitHub templates
└── 📁 workflows/
└── 📄 ci.yml # Automated testing & releases
The filter system is the heart of Kilometers CLI's extensibility:
pub trait ProxyFilter: Send + Sync {
async fn filter(&self, request: &JsonRpcRequest) -> FilterResult;
}
pub enum FilterResult {
Allow(Option<JsonRpcRequest>), // Pass through (optionally transformed)
Block(String), // Block with reason
}Built-in Filters:
- LocalLoggerFilter: Always active, logs all traffic locally
- EventSenderFilter: Sends telemetry (paid users only)
- RiskAnalysisFilter: Risk assessment and blocking (paid users only)
- JWT Authentication: API keys exchanged for short-lived JWT tokens
- Secure Credential Storage: Tokens stored in OS-native keyring (Keychain/Credential Manager/Secret Service)
- Tier-based Features: User permissions enforced server-side
- Local-first: Sensitive data never leaves your machine (free tier)
- Non-blocking Security: Security failures don't interrupt proxy operation
- Audit Trail: Complete history of all commands and decisions
# Install Rust (1.70+)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
# Install additional tools
cargo install cargo-watch # File watching
cargo install cargo-tarpaulin # Coverage
cargo install cargo-audit # Security auditinggit clone https://github.com/kilometers-ai/kilometers-cli.git
cd kilometers-cli
# Install dependencies
cargo fetch
# Set up development environment
cp .env.example .env
# Edit .env with your development API key# Development build (fast compilation, debug info)
cargo build
# Release build (optimized, production-ready)
cargo build --release
# Build with all features
cargo build --all-features
# Cross-compilation (requires cross)
cargo install cross
cross build --target x86_64-pc-windows-gnu --release# Run all tests
cargo test
# Unit tests only
cargo test --lib
# Integration tests only
cargo test --test '*'
# Specific test file
cargo test --test proxy_tests
# Specific test function
cargo test test_successful_authentication# Install coverage tool
cargo install cargo-tarpaulin
# Generate coverage report
cargo tarpaulin --out html --output-dir target/coverage/
open target/coverage/tarpaulin-report.html# Watch for changes and run tests
cargo watch -x test
# Watch and run specific tests
cargo watch -x "test proxy_tests"
# Watch and run with logging
cargo watch -x "test -- --nocapture"# Run Clippy (Rust linter)
cargo clippy
# Run with all targets and features
cargo clippy --all-targets --all-features
# Treat warnings as errors (CI mode)
cargo clippy -- -D warnings# Format all code
cargo fmt
# Check formatting without changing files
cargo fmt -- --check
# Format imports (requires rustfmt nightly)
cargo +nightly fmt# Audit dependencies for known vulnerabilities
cargo audit
# Update audit database
cargo audit --update# Set log level
export RUST_LOG=debug
cargo run -- monitor -- <command>
# Module-specific logging
export RUST_LOG=km::proxy=debug,km::auth=trace
cargo run -- monitor -- <command>
# Pretty-printed JSON logs
cargo run -- monitor -- <command> 2>&1 | jq -r 'select(.level) | "\(.timestamp) [\(.level)] \(.message)"'# Enable debug symbols in release builds
cargo build --release --config "profile.release.debug = true"
# Enable overflow checks in release
cargo build --release --config "profile.release.overflow-checks = true"# Install profiling tools
cargo install flamegraph
sudo apt-get install linux-perf # Linux only
# Generate flamegraph
cargo flamegraph --bin km -- monitor -- <command>
open flamegraph.svg# Run comprehensive checks (like CI)
./scripts/check.sh
# Update version and create release
./scripts/version.sh create
# Run integration tests
./scripts/test/run_integration_tests.sh
# Build for all platforms
./scripts/build-all.shBefore deploying to production:
- API Key: Secure API key management in place
- Logging: Log rotation and monitoring configured
- Monitoring: Health checks and alerting set up
- Security: Network policies and access controls applied
- Performance: Resource limits and scaling policies defined
- Backup: Configuration and critical data backup strategy
FROM rust:1.75-slim as builder
WORKDIR /usr/src/app
COPY . .
RUN cargo build --release --locked
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=builder /usr/src/app/target/release/km /usr/local/bin/km
USER 1000:1000
ENTRYPOINT ["km"]version: '3.8'
services:
kilometers-proxy:
image: kilometers/km:latest
environment:
- KM_API_KEY=${KM_API_KEY}
- KM_LOG_LEVEL=info
volumes:
- ./config:/root/.config/km:ro
- ./logs:/root/.local/share/km
restart: unless-stopped
command: monitor -- npx -y @modelcontextprotocol/server-filesystem /dataapiVersion: apps/v1
kind: Deployment
metadata:
name: kilometers-proxy
spec:
replicas: 3
selector:
matchLabels:
app: kilometers-proxy
template:
metadata:
labels:
app: kilometers-proxy
spec:
containers:
- name: km
image: kilometers/km:latest
env:
- name: KM_API_KEY
valueFrom:
secretKeyRef:
name: kilometers-secret
key: api-key
- name: KM_LOG_LEVEL
value: "info"
volumeMounts:
- name: config
mountPath: /root/.config/km
readOnly: true
- name: logs
mountPath: /root/.local/share/km
volumes:
- name: config
configMap:
name: kilometers-config
- name: logs
persistentVolumeClaim:
claimName: kilometers-logs[Unit]
Description=Kilometers CLI Proxy
After=network.target
Wants=network-online.target
[Service]
Type=exec
User=kilometers
Group=kilometers
ExecStart=/usr/local/bin/km monitor -- npx -y @modelcontextprotocol/server-filesystem /data
Environment=KM_API_KEY=your_api_key_here
Environment=KM_LOG_LEVEL=info
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target# Install and start the service
sudo cp kilometers.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable kilometers
sudo systemctl start kilometers
sudo systemctl status kilometers# Simple health check
km --version && echo "OK" || echo "FAIL"
# Process monitoring
ps aux | grep km | grep -v grep || echo "Process not running"
# Log file monitoring
test -f ~/.local/share/km/mcp_proxy.log && echo "Logging active" || echo "No logs"Kilometers CLI can export metrics for Prometheus monitoring:
# Enable metrics endpoint (future feature)
export KM_METRICS_ENABLED=true
export KM_METRICS_PORT=9090
# Metrics will be available at http://localhost:9090/metrics# Ship logs to centralized logging
tail -f ~/.local/share/km/mcp_proxy.log | \
while read line; do
echo "$line" | curl -X POST -d @- \
-H "Content-Type: application/json" \
https://logs.example.com/kilometers
doneQ: Why am I getting "API key not found" errors?
A: This usually means the API key isn't properly configured:
# Re-initialize with your API key
km init
# Or set via environment variable
export KM_API_KEY="km_live_your_api_key_here"
km monitor -- <command>
# Note: API keys are stored securely in your OS keyring, not in config filesQ: The proxy isn't forwarding requests properly
A: Several things to check:
# 1. Test the target server directly
npx -y @modelcontextprotocol/server-filesystem ~/Documents
# 2. Run with verbose logging
RUST_LOG=debug km monitor -- <command>
# 3. Check if ports are blocked
netstat -tulpn | grep :8080
# 4. Try a simpler command first
km monitor -- echo "test"Q: Logs are growing too large
A: Set up log rotation:
# Clear current logs
km clear-logs
# Set up log rotation (Linux/macOS)
echo "~/.local/share/km/mcp_proxy.log {
daily
rotate 7
compress
missingok
notifempty
}" | sudo tee /etc/logrotate.d/kilometersQ: How do I use this with Claude Desktop?
A: Configure Claude Desktop to use the proxy:
- Start the proxy:
km monitor -- npx -y @modelcontextprotocol/server-filesystem ~/Documents - Update Claude Desktop's MCP settings to point to
localhost:8080 - Your conversations will now be monitored and logged automatically
❌ Error: Failed to authenticate with Kilometers.ai API
Cause: Invalid API key format
🔧 Solution:
- Ensure your API key starts with 'km_live_' or 'km_test_'
- Get a new key from https://kilometers.ai/dashboard
- Run: km init --api-key "your_new_key"
❌ Error: Failed to connect to MCP server
Cause: Connection refused at localhost:8080
🔧 Solution:
- Check if the target server is running
- Verify the command syntax: km monitor -- <full-command>
- Test the server directly without the proxy
❌ Error: Permission denied writing to config directory
Cause: Insufficient permissions for ~/.config/km/
🔧 Solution:
mkdir -p ~/.config/km
chmod 755 ~/.config/km
km init
❌ Error: Too many open files
Cause: System file descriptor limit reached
🔧 Solution:
# Temporarily increase limits
ulimit -n 4096
# Permanently increase (Linux)
echo "* soft nofile 4096" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 8192" | sudo tee -a /etc/security/limits.conf
Enable comprehensive debugging:
# Maximum verbosity
export RUST_LOG=trace
export RUST_BACKTRACE=full
km monitor --verbose -- <command>
# Module-specific debugging
export RUST_LOG="km::proxy=debug,km::auth=trace,km::filters=info"
km monitor -- <command> 2>&1 | tee debug.log
# JSON log formatting
km monitor -- <command> 2>&1 | jq -r 'select(.timestamp) | "\(.timestamp) [\(.level)] \(.message)"'If you're still stuck:
- 📖 Check the Docs: kilometers.ai/docs
- 🔍 Search Issues: GitHub Issues
- 💬 Ask the Community: Discord Server
- 🐛 Report a Bug: New Issue
- ✨ Request a Feature: Feature Request
Include this information when asking for help:
# System information
km --version
rustc --version
uname -a
# Configuration
km config show
# Recent logs
tail -50 ~/.local/share/km/mcp_proxy.log- ✅ Core MCP proxy functionality
- ✅ JWT authentication system
- ✅ Filter pipeline architecture
- ✅ Local logging and telemetry
- ✅ Risk analysis for paid users
- 🔄 Comprehensive test coverage (90%+)
- 🔄 Performance optimizations
- 🔄 Windows native support
- ⏳ Configuration UI/TUI
- ⏳ Plugin system for custom filters
- ⏳ Metrics & Dashboards: Prometheus metrics, Grafana dashboards
- ⏳ Advanced Risk Analysis: ML-powered risk detection
- ⏳ Multi-tenant Support: Organization-level management
- ⏳ Performance Monitoring: Built-in profiling and diagnostics
- ⏳ Auto-scaling: Dynamic resource adjustment
- ⏳ Enhanced Security: mTLS, certificate management
- ⏳ Distributed Proxy: Multi-node proxy clusters
- ⏳ Real-time Analytics: Live usage dashboards
- ⏳ Custom Integrations: Slack, Teams, PagerDuty
- ⏳ Advanced Filtering: Custom rule engine
- ⏳ Compliance Tools: SOC2, GDPR, HIPAA reporting
- ⏳ Machine Learning: Anomaly detection, usage prediction
- AI-Powered Operations: Intelligent request routing and optimization
- Global Edge Network: Ultra-low latency worldwide deployment
- Advanced Analytics: Predictive insights and recommendations
- Enterprise Features: SSO, RBAC, audit trails
- Ecosystem Integrations: Native support for major AI platforms
We welcome contributions from developers of all skill levels! Kilometers CLI is built by the community, for the community.
- 🐛 Report Bugs: Found an issue? Report it
- ✨ Request Features: Have an idea? Share it
- 📝 Improve Docs: Fix typos, add examples, clarify instructions
- 🔧 Write Code: Implement features, fix bugs, optimize performance
- 🧪 Add Tests: Increase coverage, add edge cases, improve reliability
- 💬 Help Others: Answer questions in issues and discussions
# 1. Fork the repository on GitHub
# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/kilometers-cli.git
cd kilometers-cli
# 3. Create a feature branch
git checkout -b feat/amazing-feature
# 4. Set up development environment
cp .env.example .env
# Edit .env with your test API key
# 5. Make your changes
# ... code, test, repeat ...
# 6. Run the full test suite
cargo test
cargo clippy
cargo fmt -- --check
# 7. Commit your changes
git add .
git commit -m "feat: add amazing new feature"
# 8. Push and create a Pull Request
git push origin feat/amazing-feature- Rust Standards: Follow Rust API Guidelines
- Formatting: Use
cargo fmtwith default settings - Linting: Fix all
cargo clippywarnings - Naming: Use clear, descriptive names (prefer verbosity over brevity)
- Comments: Document public APIs and complex logic
We follow Conventional Commits:
<type>(<scope>): <description>
[optional body]
[optional footer]
Types:
feat:New featurefix:Bug fixdocs:Documentation changesstyle:Formatting, missing semicolons, etc.refactor:Code restructuringperf:Performance improvementstest:Add or modify testschore:Build process, dependencies, etc.
Examples:
feat(auth): add JWT token refresh mechanism
fix(proxy): handle connection timeouts gracefully
docs(readme): update installation instructions
test(filters): add unit tests for risk analysis- Unit Tests: Cover all public functions and critical logic
- Integration Tests: Test complete workflows end-to-end
- Error Handling: Test failure modes and edge cases
- Performance: Benchmark performance-critical code
# Run tests before submitting PR
cargo test --all
cargo test --all --release
cargo clippy --all-targets -- -D warnings- Create Issue First: For significant changes, create an issue to discuss the approach
- Small PRs: Keep changes focused and atomic
- Clear Description: Explain what changes and why
- Tests Included: Add tests for new functionality
- Documentation: Update docs for user-facing changes
- CI Passing: All checks must pass
- Review Process: Address feedback promptly and professionally
Contributors are recognized in multiple ways:
- Contributors Section: Listed in README and changelog
- GitHub Insights: Automatic contribution tracking
- Special Thanks: Major contributors highlighted in releases
- Swag: Stickers and shirts for significant contributions
- Architecture Guide: ARCHITECTURE.md
- API Documentation: docs.rs/km
- Design Decisions: docs/decisions/
- Contribution Guide: CONTRIBUTING.md
- Code of Conduct: CODE_OF_CONDUCT.md
Join our growing community of developers, DevOps engineers, and AI enthusiasts!
Discord Server Real-time chat & support |
GitHub Discussions Feature discussions & Q&A |
Updates & announcements |
- 🔔 Watch this repo for release notifications
- ⭐ Star us to show your support
- 🐦 Follow @kilometers_ai for updates
- 📧 Subscribe to our newsletter at kilometers.ai
- Monthly Community Calls: First Thursday of each month
- Contributor Office Hours: Wednesdays 2-3 PM PST
- Workshop Series: Bi-weekly technical deep dives
- Hackathons: Quarterly community challenges
Special thanks to our amazing contributors:
- @milesangelo - Core Maintainer
- @contributor2 - Security & Performance
- @contributor3 - Documentation & Community
For organizations requiring:
- Priority Support: 24/7 technical assistance
- Custom Integrations: Tailored solutions and consulting
- Training: Team workshops and certification programs
- SLAs: Guaranteed response times and uptime
Contact us at: enterprise@kilometers.ai
Kilometers CLI is released under the MIT License. See LICENSE for details.
MIT License
Copyright (c) 2025 Kilometers AI
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
This project includes dependencies with various open-source licenses:
- Tokio: MIT License
- Serde: MIT/Apache-2.0
- Clap: MIT/Apache-2.0
- Reqwest: MIT/Apache-2.0
For a complete list, see THIRD_PARTY_LICENSES.md.
Built with ❤️ by the Kilometers AI team and amazing contributors
⭐ Like this project? Give us a star and follow @kilometers_ai for updates!