Koda CLI

Koda CLI is an open-source AI agent that brings the power of Koda directly into your terminal. It provides lightweight access to Koda, giving you the most direct path from your prompt to our model.

🚀 Why Koda CLI?

• 🎯 Free tier: Generous trial limits available with GitHub sign-in
• 🧠 Powerful Koda 2.5 Pro: Access to 1M token context window
• 🔧 Built-in tools: Web search grounding, file operations, shell commands, web fetching
• 🔌 Extensible: MCP (Model Context Protocol) support for custom integrations
• 💻 Terminal-first: Designed for developers who live in the command line
• 🛡️ Open source: Apache 2.0 licensed

📦 Installation

Quick Install

Run instantly with npx

# Using npx (no installation required)
npx https://github.com/koda-ai/koda-cli

Install globally with npm

npm install -g @koda-ai/koda-cli

Install globally with Homebrew (macOS/Linux)

brew install koda-cli

System Requirements

• Node.js version 20 or higher
• macOS, Linux, or Windows

📋 Key Features

Code Understanding & Generation

• Query and edit large codebases
• Generate new apps from PDFs, images, or sketches using multimodal capabilities
• Debug issues and troubleshoot with natural language

Automation & Integration

• Automate operational tasks like querying pull requests or handling complex rebases
• Use MCP servers to connect new capabilities, including media generation with Imagen, Veo or Lyria
• Run non-interactively in scripts for workflow automation

Advanced Capabilities

• Ground your queries with built-in web search for real-time information
• Conversation checkpointing to save and resume complex sessions
• Custom context files (KODA.md) to tailor behavior for your projects

GitHub Integration

Integrate Koda CLI directly into your GitHub workflows with Koda CLI GitHub Action:

• Pull Request Reviews: Automated code review with contextual feedback and suggestions
• Issue Triage: Automated labeling and prioritization of GitHub issues based on content analysis
• On-demand Assistance: Mention @koda-cli in issues and pull requests for help with debugging, explanations, or task delegation
• Custom Workflows: Build automated, scheduled and on-demand workflows tailored to your team's needs

🔐 Authentication Options

Choose the authentication method that best fits your needs:

Option 1: Sign in with GitHub (recommended)

✨ Best for: Most users who want the hosted free tier or organization-managed seats.

Benefits:

• No manual key rotation – the CLI performs the GitHub device flow and caches tokens securely.
• Automatic provisioning – optionally exchange the GitHub token for a managed Koda API key.
• Shared configuration – credentials are stored in ~/.config/koda/credentials.json for reuse.

1. Ensure the CLI has access to a GitHub OAuth client ID. Packaged releases ship with one. If you are running from source, create a GitHub OAuth App with Device Flow enabled and export GITHUB_CLIENT_ID=<your-client-id>. You can customise scopes with GITHUB_SCOPES (defaults to read:user user:email).
2. Launch the CLI and choose Sign in with GitHub when prompted. The terminal prints a verification URL and code; open the URL, enter the code, and approve the request.
3. (Optional) Set KODA_GITHUB_EXCHANGE_URL to the endpoint provided by your Koda administrator to automatically mint a long-lived API key from the GitHub token. The CLI saves any tokens that are issued into ~/.config/koda/credentials.json and makes them available for future sessions.

koda

Option 2: Provide a Koda API key

✨ Best for: Service accounts, CI jobs, or teams managing credentials centrally.

Benefits:

• Deterministic access – use the exact seat or quota assigned to the key.
• Script friendly – works in headless and automated environments.
• Compatible – works with cached GitHub tokens or explicit KODA_API_KEY secrets.

export KODA_API_KEY="YOUR_API_KEY"
koda

Store the variable in an .env file, your shell profile, or ~/.config/koda/credentials.json to reuse it across sessions.

Option 3: Continue without authentication (limited)

✨ Best for: Exploring the interface or running local-only commands before connecting to the service.

You can skip authentication from the initial dialog or select Skip later via /auth. Model-backed features remain disabled until you sign in with GitHub or provide an API key.

For detailed setup instructions, troubleshooting tips, and environment variable options see the authentication guide.

🚀 Getting Started

Basic Usage

Start in current directory

koda

Include multiple directories

koda --include-directories ../lib,../docs

Use specific model

koda -m koda-pro

Non-interactive mode for scripts

koda -p "Explain the architecture of this codebase"

Quick Examples

Start a new project

cd new-project/
koda
> Write me a Discord bot that answers questions using a FAQ.md file I will provide

#### Analyze existing code
```bash
git clone https://github.com/koda-ai/koda-cli
cd koda-cli
koda
> Give me a summary of all of the changes that went in yesterday

📚 Documentation

Getting Started

• Quickstart Guide - Get up and running quickly
• Authentication Setup - Detailed auth configuration
• Configuration Guide - Settings and customization
• Keyboard Shortcuts - Productivity tips

Core Features

• Commands Reference - All slash commands (/help, /chat, /mcp, etc.)
• Checkpointing - Save and resume conversations
• Memory Management - Using KODA.md context files
• Token Caching - Optimize token usage

Tools & Extensions

• Built-in Tools Overview
  • File System Operations
  • Shell Commands
  • Web Fetch & Search
  • Multi-file Operations
• MCP Server Integration - Extend with custom tools
• Custom Extensions - Build your own commands

Advanced Topics

• Architecture Overview - How Koda CLI works
• IDE Integration - VS Code companion
• Sandboxing & Security - Safe execution environments
• Enterprise Deployment - Docker, system-wide config
• Telemetry & Monitoring - Usage tracking
• Tools API Development - Create custom tools

Configuration & Customization

• Settings Reference - All configuration options
• Theme Customization - Visual customization
• .koda Directory - Project-specific settings
• Environment Variables

Troubleshooting & Support

• Troubleshooting Guide - Common issues and solutions
• FAQ - Quick answers
• Use /bug command to report issues directly from the CLI

Using MCP Servers

Configure MCP servers in ~/.koda/settings.json to extend Koda CLI with custom tools:

> @github List my open pull requests
> @slack Send a summary of today's commits to #dev channel
> @database Run a query to find inactive users

See the MCP Server Integration guide for setup instructions.

🤝 Contributing

We welcome contributions! Koda CLI is fully open source (Apache 2.0), and we encourage the community to:

• Report bugs and suggest features
• Improve documentation
• Submit code improvements
• Share your MCP servers and extensions

See our Contributing Guide for development setup, coding standards, and how to submit pull requests.

Check our Official Roadmap for planned features and priorities.

🧭 Documentation Site

The Markdown guides in docs/ are published with a lightweight Docusaurus site located in docs-website/. To work on the docs UI locally:

• npm run docs:install (first time only) installs the isolated Docusaurus dependencies.
• npm run docs:start launches the development server at http://localhost:3000.
• npm run docs:build creates a production static build under docs-website/build/.

The docs folder is excluded from the main CLI bundle, so these commands are entirely optional for regular builds.

📖 Resources

• Official Roadmap - See what's coming next
• NPM Package - Package registry
• GitHub Issues - Report bugs or request features
• Security Advisories - Security updates

Uninstall

See the Uninstall Guide for removal instructions.

📄 Legal

• License: Apache License 2.0
• Terms of Service: Terms & Privacy
• Security: Security Policy