Terra Code CLI

🧠 What Makes Terra Unique

🔗 Enterprise Knowledge Management

🚀 Enhanced AI Responses

🔍 Intelligent Code Analysis

🔄 Multi-Model Support

💾 Persistent Memory

Installation

Prerequisites

curl -qL https://www.npmjs.com/install.sh | sh

Install from npm

npm install -g @terra-code/terra-code@latest
terra --version

Install from source

git clone https://github.com/TerraAGI/terra-code-cli.git
cd terra-code-cli
npm install
npm install -g .

Quick Start

# Start Terra Code CLI
terra

# Example commands
> Explain this codebase structure
> Help me refactor this function
> Generate unit tests for this module

🧠 Development Brain

# Upload documents to your brain (supports .txt, .md, .docx, .pdf)
terra> /brain upload online_order_flow.md
✅ Document uploaded successfully to your Terra brain

# Interactive Knowledge Transfer sessions
terra> /brain kt
🧠 Starting Knowledge Transfer session...

# Remember personal facts
terra> /brain remember "I prefer TypeScript over JavaScript"
🧠 Remembering: "I prefer TypeScript over JavaScript"

# Index your codebase for semantic search (requires VoyageAI API key)
terra> /semantic index .
🔍 Starting semantic indexing...

Session Management

Configure Session Token Limit

{
  "sessionTokenLimit": 32000
}

Session Commands

Authorization

1. Qwen OAuth (🚀 Recommended - Start in 30 seconds)

# Just run this command and follow the browser authentication
terra

2. OpenAI-Compatible API

Configuration Methods

{
  "openaiApiKey": "your_api_key_here",
  "openaiBaseUrl": "your_api_endpoint",
  "openaiModel": "your_model_choice"
}

export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL="your_api_endpoint"
export OPENAI_MODEL="your_model_choice"

$env:OPENAI_API_KEY="your_api_key_here"
$env:OPENAI_BASE_URL="your_api_endpoint"
$env:OPENAI_MODEL="your_model_choice"

Quick Start Example

{
  "openaiApiKey": "sk-or-v1-your-key-here",
  "openaiBaseUrl": "https://openrouter.ai/api/v1",
  "openaiModel": "qwen/qwen3-coder"
}

# Set environment variables
export OPENAI_API_KEY="sk-or-v1-your-key-here"
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_MODEL="qwen/qwen3-coder"

# Start Terra
terra

$env:OPENAI_API_KEY="sk-or-v1-your-key-here"
$env:OPENAI_BASE_URL="https://openrouter.ai/api/v1"
$env:OPENAI_MODEL="qwen/qwen3-coder"
terra

API Provider Options

🇨🇳 For Users in Mainland China

export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
export OPENAI_MODEL="qwen3-coder-plus"

export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL="https://api-inference.modelscope.cn/v1"
export OPENAI_MODEL="Qwen/Qwen3-Coder-480B-A35B-Instruct"

🌍 For International Users

export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
export OPENAI_MODEL="qwen3-coder-plus"

export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_MODEL="qwen/qwen3-coder:free"

3. VoyageAI API Key Setup when free creds (for Semantic Search)

User Settings Configuration

cd %USERPROFILE%\.terra
notepad settings.json

cd ~/.terra
nano settings.json

{
  "semantic": {
    "enabled": true,
    "voyageAI": {
      "apiKey": "your-voyageai-api-key-here",
      "model": "voyage-code-3",
      "baseURL": "https://api.voyageai.com/v1"
    }
  }
}

Getting Your VoyageAI API Key

Verify Configuration

# Check if semantic features are available
terra> /semantic status

# Index your current project
terra> /semantic index .

Usage Examples

🔍 Explore Codebases

cd your-project/
terra

# Architecture analysis
> Describe the main pieces of this system's architecture
> What are the key dependencies and how do they interact?
> Find all API endpoints and their authentication methods

💻 Code Development

# Refactoring
> Refactor this function to improve readability and performance
> Convert this class to use dependency injection
> Split this large module into smaller, focused components

# Code generation
> Create a REST API endpoint for user management
> Generate unit tests for the authentication module
> Add error handling to all database operations

🔄 Automate Workflows

# Git automation
> Analyze git commits from the last 7 days, grouped by feature
> Create a changelog from recent commits
> Find all TODO comments and create GitHub issues

# File operations
> Convert all images in this directory to PNG format
> Rename all test files to follow the *.test.ts pattern
> Find and remove all console.log statements

🐛 Debugging & Analysis

# Performance analysis
> Identify performance bottlenecks in this React component
> Find all N+1 query problems in the codebase

# Security audit
> Check for potential SQL injection vulnerabilities
> Find all hardcoded credentials or API keys

Popular Tasks

📚 Understand New Codebases

> What are the core business logic components?
> What security mechanisms are in place?
> How does the data flow through the system?
> What are the main design patterns used?
> Generate a dependency graph for this module

🔨 Code Refactoring & Optimization

> What parts of this module can be optimized?
> Help me refactor this class to follow SOLID principles
> Add proper error handling and logging
> Convert callbacks to async/await pattern
> Implement caching for expensive operations

📝 Documentation & Testing

> Generate comprehensive JSDoc comments for all public APIs
> Write unit tests with edge cases for this component
> Create API documentation in OpenAPI format
> Add inline comments explaining complex algorithms
> Generate a README for this module

🚀 Development Acceleration

> Set up a new Express server with authentication
> Create a React component with TypeScript and tests
> Implement a rate limiter middleware
> Add database migrations for new schema
> Configure CI/CD pipeline for this project

Commands & Shortcuts

Core Commands

Brain Commands (Priority)

Semantic Analysis Commands (Optional)

Keyboard Shortcuts

Development & Contributing

Troubleshooting

Acknowledgments

License

Repository

Website & Support

Contributing