Kilo CLI Complete Operating Guide

1. Install Kilo CLI

1.1 macOS / Linux Installation

Run the following command in Terminal to install Kilo CLI:

bash

npm install -g @kilocode/cli

Verify successful installation:

bash

kilo --version

1.2 Windows Installation

Execute in PowerShell (run as Administrator):

powershell

npm install -g @kilocode/cli

Verify installation:

powershell

kilo --version

Tip: Make sure PowerShell has been added to the PATH environment variable. If not added, you need to:
Open "Edit system environment variables"
Click "Environment Variables"
Select Path in system variables → Edit → New
Add: C:\Windows\System32\WindowsPowerShell\v1.0\
Click OK and restart PowerShell

2. TokenSwitch API Relay Configuration

2.1 Get API Key

Visit using your browser: https://neolink.com/
Login with the account assigned by administrator
Click "API Key" in the left menu
Click "Create API Key" button
Save the generated API Key

2.2 Configuration Methods

Kilo CLI supports three ways to configure TokenSwitch API, with priority from high to low:

Configuration File (Recommended) - Supports kilo.jsonc, kilo.json, opencode.jsonc and other formats
Environment Variables
Startup Parameters

Method 1: Configuration File (Recommended)

Create a configuration file in the project root or global configuration directory:

Project-level Configuration:

./kilo.jsonc or ./kilo.json
./.kilo/kilo.jsonc or ./.kilo/kilo.json
./opencode.jsonc or ./opencode.json (compatible format)
./.kilo/opencode.jsonc or ./.kilo/opencode.json (compatible format)

Global Configuration:

~/.config/kilo/kilo.jsonc or ~/.config/kilo/kilo.json
~/.config/kilo/opencode.jsonc or ~/.config/kilo/opencode.json (compatible format)

Add the following content to the configuration file (minimum configuration):

jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "tokenswitch": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "TokenSwitch",
      "options": {
        "baseURL": {{apiUrl}},
        "apiKey": "your_API_KEY"
      },
      "models": {
        "cl-so-4.6": {
          "name": "Claude Sonnet 4.6"
        },
        "cl-ha-4.5-1001": {
          "name": "Claude Haiku 4.5"
        }
      }
    }
  }
}

Complete configuration example (including permissions and timeout settings):

jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "default_model": "cl-so-4.6",
  "provider": {
    "tokenswitch": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "TokenSwitch",
      "options": {
        "baseURL": {{apiUrl}},
        "apiKey": "your_API_KEY",
        "timeout": 300000
      },
      "models": {
        "cl-so-4.6": {
          "name": "Claude Sonnet 4.6"
        },
        "cl-ha-4.5-1001": {
          "name": "Claude Haiku 4.5"
        }
      }
    }
  },
  "permission": {
    "bash": "ask",
    "edit": "ask",
    "read": "allow"
  }
}

Security Tip: If you commit configuration files to a version control system, ensure API Key is not tracked. Recommendations:
Use environment variables to store sensitive information
Add configuration files (kilo.jsonc, opencode.jsonc, etc.) to .gitignore
Or use environment variable references for API Key in configuration files

Method 2: Environment Variables

macOS / Linux Configuration

For zsh (macOS default):

bash

echo 'export TOKENSWITCH_BASE_URL={{apiUrl}}' >> ~/.zshrc
echo 'export TOKENSWITCH_API_KEY="your_API_KEY"' >> ~/.zshrc
source ~/.zshrc

For bash:

bash

echo 'export TOKENSWITCH_BASE_URL={{apiUrl}}' >> ~/.bash_profile
echo 'export TOKENSWITCH_API_KEY="your_API_KEY"' >> ~/.bash_profile
source ~/.bash_profile

Verify configuration:

bash

echo $TOKENSWITCH_BASE_URL
echo $TOKENSWITCH_API_KEY

Windows Configuration

Run the following commands in PowerShell to set user-level environment variables:

powershell

[System.Environment]::SetEnvironmentVariable("TOKENSWITCH_BASE_URL", {{apiUrl}}, [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable("TOKENSWITCH_API_KEY", "your_API_KEY", [System.EnvironmentVariableTarget]::User)

After completion, restart PowerShell to verify:

powershell

$env:TOKENSWITCH_BASE_URL
$env:TOKENSWITCH_API_KEY

Method 3: Startup Parameters

Start Kilo CLI and specify TokenSwitch API configuration (temporary solution):

bash

kilo --base-url {{apiUrl}} --api-key your_API_KEY

Or use environment variables:

bash

TOKENSWITCH_BASE_URL={{apiUrl}}
TOKENSWITCH_API_KEY=your_API_KEY kilo

2.3 Configuration File Priority

Kilo CLI loads configuration in the following order (later loaded will override previously loaded):

Priority	Configuration Location	Description
1 (Lowest)	`/etc/kilo/` (Linux) or `/Library/Application Support/kilo/` (macOS) or `%ProgramData%\kilo\` (Windows)	Enterprise/Administrator configuration
2	`~/.config/kilo/kilo.jsonc`	Global user configuration
3	Environment variable `KILO_CONFIG`	Specified configuration file
4	`./kilo.jsonc` or `./opencode.jsonc`	Project root configuration
5	`./.kilo/kilo.jsonc` or `./.kilo/opencode.jsonc`	Project .kilo directory configuration (highest priority)
6 (Highest)	Environment variable `KILO_CONFIG_CONTENT`	Inline JSON configuration

2.4 Complete Startup Parameters

Start Kilo CLI using configuration file:

bash

cd /path/to/your/project
kilo

Kilo will automatically find and load the configuration file.

3. File Path and Loading Considerations

3.1 Project Working Directory

Kilo CLI needs to be run in the project root directory. Run the following command to start Kilo:

bash

cd /path/to/your/project
kilo

3.2 CLAUDE.md File

Create a CLAUDE.md file in the project root to store project standards and configuration:

bash

# Create CLAUDE.md in project root
cat > CLAUDE.md << 'EOF'
# Project Standards

## Code Standards
- Use TypeScript
- Test framework: Vitest
- Indent: 2 spaces
- Linter: ESLint

## Project Structure
- src/: Source code
- tests/: Test files
- docs/: Documentation

## Other Notes
- Run `npm run lint` and `npm run test` before committing
- Pull Requests must pass all tests
EOF

Benefits:

No need to repeat project standards in every conversation
Reduce input token consumption
Ensure AI understands project-specific requirements

3.3 File Loading Path

Explicitly Specify File Path

Reference project files explicitly in prompts:

bash

kilo "Analyze the permission verification logic in src/auth/login.ts"

Reference Logs and File Content

bash

kilo "Fix the 500 error when user logs in, refer to error message in logs/error.log"

View Specific Files

bash

# Let Kilo view and explain code
kilo "Explain the database connection configuration in config/database.ts"

3.4 Path Considerations

Item	Description
Working Directory	Must run `kilo` in project root
Relative Paths	All file paths are relative to project root
CLAUDE.md	Place in project root, automatically loaded
Log Files	Use relative paths: `logs/error.log`
Code Files	Prefer relative paths: `src/services/user.ts`

4. Common Built-in Commands

4.1 Basic Commands

In the Kilo CLI interactive interface, you can use slash commands:

Command	Description
`/clear`	Clear current session and start new conversation
`/config`	View and modify Kilo configuration
`/model`	Switch AI model
`/help`	Show help information
`/exit`	Exit Kilo CLI

4.2 Session Management - `/clear`

Use /clear immediately after completing a task:

bash

# After fixing bug
/clear

Benefits:

Clear outdated context
Reduce unnecessary token consumption
Start new independent task

4.3 Model Switching - `/model`

View available models and switch:

bash

/model

Select model appropriate for the task:

Simple tasks: Use lightweight model (save cost)
Complex analysis: Use advanced model (higher accuracy)

4.4 Configuration Management - `/config`

View and adjust configuration parameters:

bash

/config

Common configuration items:

MAX_THINKING_TOKENS: Control model thinking budget
API_KEY: API key
BASE_URL: API endpoint address

Adjust thinking budget (simple tasks):

bash

/config MAX_THINKING_TOKENS 1000

4.5 Common Workflows

Code Exploration

bash

# Understand project structure
kilo "What are the main modules in this project? How is the directory structure organized?"

# Explain certain feature
kilo "Explain the payment flow implementation in src/services/payment.ts"

# Find related code
kilo "Which files in the project handle error logging?"

Bug Fixing

bash

# Fix specific error
kilo "Fix the 500 error when user logs in, refer to logs/error.log"

# Clear context after completion
/clear

# Start next task
kilo "Implement user registration feature"

Code Generation

bash

# Generate test cases
kilo "Write unit tests for auth.service.ts and run"

# Automate refactoring
kilo "Update all deprecated API calls to v2 version in the project and run lint"

# Generate documentation
kilo "Generate OpenAPI documentation for all APIs in src/api/ directory"

5. Usage Tips

5.1 Optimize Token Consumption

Create CLAUDE.md Standards File

Avoid repeating project standards every time:

bash

# Define project standards once
cat > CLAUDE.md << 'EOF'
# Project Standards
- TypeScript strict mode
- ESLint checking
- Jest test framework
- 2 space indent
EOF

Control Thinking Budget

For simple tasks, lower thinking budget:

bash

/config MAX_THINKING_TOKENS 500

Use /clear Promptly

bash

# Clear immediately after completing task
/clear

5.2 Improve Code Quality

Use Plan Mode

Before making large-scale changes, let Kilo make a plan first:

bash

# Press Tab key to enter Plan Mode
# Or explicitly request planning in prompt
kilo "Plan: Steps to refactor auth module"

Verify Modifications

bash

# Let Kilo run tests to verify
kilo "After fixing bug, please run npm test to verify all tests pass"

5.3 Best Practices

Practice	Description
✅ Create CLAUDE.md	Define project standards, reduce token consumption
✅ `/clear` promptly	Clear session after task completion
✅ Specify files explicitly	Use relative paths to reference specific files
✅ One task at a time	Avoid mixing multiple requirements
❌ Long sessions	Avoid chatting too long in one session
❌ Vague descriptions	Avoid unclear requirement descriptions
❌ Ignore errors	Handle and verify modifications promptly

6. Troubleshooting

6.1 Environment Variable Not Taking Effect

macOS/Linux:

bash

# Confirm configuration file is updated
cat ~/.zshrc | grep TOKENSWITCH

# Reload configuration
source ~/.zshrc

Windows:

powershell

# Restart PowerShell to make variable take effect
# Or check environment variables
Get-ChildItem env:TOKENSWITCH_*

6.2 API Connection Failed

Check configuration:

bash

# Verify API URL
echo $TOKENSWITCH_BASE_URL

# Verify API Key
echo $TOKENSWITCH_API_KEY

# Test connection
kilo "hello"

Ensure:

API URL correct:
API Key valid and not expired
Network connection normal
If using configuration file method, check provider configuration in kilo.jsonc or opencode.jsonc

6.3 Model Unavailable

Switch to available model:

bash

/model
# Select available model from list

7. More Resources

Official Documentation: https://kilo.ai/docs
GitHub Repository: https://github.com/Kilo-Org/kilocode
Community Support: https://kilo.ai/discord
Issue Feedback: https://github.com/Kilo-Org/kilocode/issues

MiniMax/hailuo

MiniMax-H3

MiniMax

Suno

OpenAI Compatible API

Seedance Resource Management

Kilo CLI Complete Operating Guide ​

1. Install Kilo CLI ​

1.1 macOS / Linux Installation ​

1.2 Windows Installation ​

2. TokenSwitch API Relay Configuration ​

2.1 Get API Key ​

2.2 Configuration Methods ​

Method 1: Configuration File (Recommended) ​

Method 2: Environment Variables ​

macOS / Linux Configuration ​

Windows Configuration ​

Method 3: Startup Parameters ​

2.3 Configuration File Priority ​

2.4 Complete Startup Parameters ​

3. File Path and Loading Considerations ​

3.1 Project Working Directory ​

3.2 CLAUDE.md File ​

3.3 File Loading Path ​

Explicitly Specify File Path ​

Reference Logs and File Content ​

View Specific Files ​

3.4 Path Considerations ​

4. Common Built-in Commands ​

4.1 Basic Commands ​

4.2 Session Management - /clear ​

4.3 Model Switching - /model ​

4.4 Configuration Management - /config ​

4.5 Common Workflows ​

Code Exploration ​

Bug Fixing ​

Code Generation ​

5. Usage Tips ​

5.1 Optimize Token Consumption ​

5.2 Improve Code Quality ​

5.3 Best Practices ​

6. Troubleshooting ​

6.1 Environment Variable Not Taking Effect ​

6.2 API Connection Failed ​

6.3 Model Unavailable ​

7. More Resources ​

Kilo CLI Complete Operating Guide

1. Install Kilo CLI

1.1 macOS / Linux Installation

1.2 Windows Installation

2. TokenSwitch API Relay Configuration

2.1 Get API Key

2.2 Configuration Methods

Method 1: Configuration File (Recommended)

Method 2: Environment Variables

macOS / Linux Configuration

Windows Configuration

Method 3: Startup Parameters

2.3 Configuration File Priority

2.4 Complete Startup Parameters

3. File Path and Loading Considerations

3.1 Project Working Directory

3.2 CLAUDE.md File

3.3 File Loading Path

Explicitly Specify File Path

Reference Logs and File Content

View Specific Files

3.4 Path Considerations

4. Common Built-in Commands

4.1 Basic Commands

4.2 Session Management - `/clear`

4.3 Model Switching - `/model`

4.4 Configuration Management - `/config`

4.5 Common Workflows

Code Exploration

Bug Fixing

Code Generation

5. Usage Tips

5.1 Optimize Token Consumption

5.2 Improve Code Quality

5.3 Best Practices

6. Troubleshooting

6.1 Environment Variable Not Taking Effect

6.2 API Connection Failed

6.3 Model Unavailable

7. More Resources