Configuration

Kodezi CLI offers a highly flexible configuration system that allows you to customize how the CLI behaves globally and within individual projects.

This guide explains where configuration files are stored, how settings are layered, and how to adjust them to match your workflow.

Configuration Files

Kodezi CLI reads configuration from multiple locations depending on scope, global settings, runtime updated settings, and optional project level overrides.

Global Config

The global config contains:

• Authentication credentials
• Default LSP and MCP configuration
• Global context paths
• Debugging settings

This file is created automatically the first time you authenticate.

Linux/macOS:

~/.config/kodezi-cli/kodezi-cli.json

Windows:

%LOCALAPPDATA%\kodezi-cli\kodezi-cli.json

Stores authentication, global options, and defaults.

Global Data Config

This file is used internally by the CLI to store runtime updated values, such as:

• Last used directories
• Compact view state
• Temporary preferences

Do not manually edit this file unless you know exactly what you are modifying.

Linux/macOS:

~/.local/share/kodezi-cli/kodezi-cli.json

Windows:

%LOCALAPPDATA%\kodezi-cli\kodezi-cli.json

Used when the CLI updates configuration at runtime (e.g., setting compact mode).

Project Config

A project specific configuration overrides global values when you are inside a repository.
This is useful when different projects require:

• Different LSP servers
• Custom MCP toolchains
• Per project context paths
• Unique debugging configuration

Supported filenames:

kodezi-cli.json 
or 
.kodezi-cli.json

Basic Configuration

Below is an example of a realistic, complete config:

{
  "auth": {
    "email": "user@example.com",
    "token": "your-auth-token"
  },
  "lsp": {
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"]
    }
  },
  "mcp": {
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["@kodezi/mcp-database"]
    }
  },
  "options": {
    "context_paths": ["ARCHITECTURE.md"],
    "debug": false
  }
}

Configuration Sections

Each of the following configuration areas has its own dedicated guide:

Configuration Priority

Kodezi CLI merges configuration files in a strict order. Later entries override earlier ones:

1. Built in defaults
2. Global config (~/.config/kodezi-cli/kodezi-cli.json)
3. Global data config (~/.local/share/kodezi-cli/kodezi-cli.json)
4. Project config (kodezi-cli.json or .kodezi-cli.json)
5. Environment variables
6. Command line flags

Command Line Flags

You can override configuration values temporarily using flags:

kodezi --cwd /path/to/project     # -c: Working directory
kodezi --data-dir /custom/dir     # -D: Data directory
kodezi --debug                    # -d: Debug logging
kodezi --yolo                     # -y: Auto approve all

Environment Variables

Environment variables override config files but are lower priority than flags.

# Skip authentication (development only)
export KODEZI_CLI_SKIP_AUTH="true"

# Disable metrics
export KODEZI_CLI_DISABLE_METRICS="true"
export DO_NOT_TRACK="true"

View Configuration

Use these commands to inspect your setup:

# Show config and data directories
kodezi dirs

# View current config
cat ~/.config/kodezi-cli/kodezi-cli.json

# Generate JSON schema
kodezi schema > schema.json

Authentication

# Login
kodezi auth login

# Logout
kodezi auth logout

# Check status
kodezi auth status

Next Steps

• LSP Setup - Enable code intelligence
• MCP Setup - Extend capabilities
• Context Files - Provide custom context
• Settings Reference - All options