Introduction

CLIAI is a completely free and open-source command-line AI assistant that helps you with terminal commands, system administration, and general questions.

Key Features

🔒 Privacy-First: Local AI processing with Ollama - your data never leaves your machine
🔑 Bring Your Own Key: Use your own OpenAI, Anthropic, or other LLM API keys
🆓 Completely Free: No subscriptions, no hidden costs - 100% open source
🛡️ Safety-Focused: Multi-level command validation and safety checks
⚡ Fast & Reliable: Built-in performance monitoring and circuit breakers

CLIAI bridges the gap between natural language and command-line operations. Instead of searching documentation or Stack Overflow, simply ask CLIAI what you want to do, and it will generate the appropriate command with explanations.

Supported Platforms

Linux (x86_64, ARM64)
macOS (Intel, Apple Silicon)
Windows (x86_64)

Installation

Quick Install

One-Line Install (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/bytestrix/cliai/main/install.sh | bash

Cargo (All Platforms)

cargo install cliai

Package Managers

Arch Linux (AUR)

yay -S cliai

Ubuntu/Debian

wget https://github.com/bytestrix/cliai/releases/latest/download/cliai.deb
sudo dpkg -i cliai.deb

macOS (Homebrew)

brew tap bytestrix/tap
brew install cliai

Windows (Chocolatey)

choco install cliai

From Source

git clone https://github.com/bytestrix/cliai.git
cd cliai
cargo build --release
sudo cp target/release/cliai /usr/local/bin/

Prerequisites

For local AI processing (recommended):

Ollama - Install Ollama

For cloud AI:

OpenAI API key, or
Anthropic API key

Quick Start

Setup

Option 1: Local AI (Ollama)

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a model
ollama pull mistral

# Configure CLIAI
cliai select mistral

Option 2: Cloud AI

# Set your API key
cliai set-key openai sk-your-key-here

# Or use Anthropic
cliai set-key anthropic your-key-here

# Select model
cliai select gpt-4

First Commands

# Ask for help
cliai "how do I list all files including hidden ones?"

# System administration
cliai "check disk usage"

# File operations
cliai "find all Python files modified in the last week"

# Git operations
cliai "show me the last 5 commits"

Custom Prefix

Set a custom command prefix:

cliai set-prefix ai
# Now use: ai "your question"

Configuration

Configuration File

CLIAI stores configuration in ~/.config/cliai/config.toml:

model = "mistral"
provider = "ollama"
auto_execute = false
dry_run = false
safety_level = "Medium"
context_timeout = 5000
ollama_url = "http://localhost:11434"
prefix = "cliai"

Commands

Model Management

# List available models
cliai list-models

# Select a model
cliai select mistral

# List providers
cliai list-providers

API Key Management

# Set API key
cliai set-key openai sk-...

# Test connection
cliai test-key openai

# Remove key
cliai remove-key openai

Safety Settings

# Set safety level
cliai safety-level high    # Maximum safety
cliai safety-level medium  # Balanced (default)
cliai safety-level low     # Minimal checks

# Enable auto-execution
cliai auto-execute --enable

# Enable dry-run mode
cliai dry-run --enable

Other Settings

# View current configuration
cliai config

# Clear chat history
cliai clear

# Check provider status
cliai provider-status

# View performance metrics
cliai performance-status

Basic Commands

Command Syntax

cliai "your question or request"

Examples

File Operations

cliai "list all files in current directory"
cliai "find files larger than 100MB"
cliai "compress this folder"
cliai "extract archive.tar.gz"

System Information

cliai "check disk usage"
cliai "show memory usage"
cliai "list running processes"
cliai "what's my IP address?"

Git Operations

cliai "show git status"
cliai "create a new branch"
cliai "undo last commit"
cliai "show commit history"

Network Operations

cliai "test internet connection"
cliai "download file from URL"
cliai "check if port 8080 is open"

Package Management

cliai "install package nginx"
cliai "update all packages"
cliai "search for package python"

AI Providers

CLIAI supports multiple AI providers for maximum flexibility.

Ollama (Local)

Recommended for privacy and offline use

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull models
ollama pull mistral
ollama pull llama2
ollama pull codellama

# Configure CLIAI
cliai select mistral

Advantages:

Complete privacy
No API costs
Works offline
Fast responses

OpenAI

# Set API key
cliai set-key openai sk-your-key-here

# Select model
cliai select gpt-4
cliai select gpt-3.5-turbo

Available Models:

gpt-4
gpt-4-turbo
gpt-3.5-turbo

Anthropic

# Set API key
cliai set-key anthropic your-key-here

# Select model
cliai select claude-3-sonnet
cliai select claude-3-haiku
cliai select claude-3-opus

Available Models:

claude-3-opus
claude-3-sonnet
claude-3-haiku

Provider Fallback

CLIAI automatically falls back to alternative providers if the primary one fails:

Try local Ollama first (if configured)
Fall back to cloud provider (if API key set)
Circuit breaker prevents repeated failures

Safety Features

CLIAI includes multiple layers of safety to protect your system.

Safety Levels

High (Recommended for beginners)

Blocks dangerous operations
Requires confirmation for system changes
Maximum validation

Medium (Default)

Balanced safety and convenience
Confirms risky operations
Standard validation

Low (Experienced users)

Minimal safety checks
Allows most operations
Basic validation only

Command Validation

Every command goes through multiple validation layers:

Syntax Checking: Validates shell syntax
Placeholder Detection: Catches AI hallucinations
Risk Assessment: Categorizes command danger level
Pattern Matching: Detects known dangerous patterns

Dangerous Patterns Detected

rm -rf / - System deletion
dd if=/dev/zero - Disk wiping
chmod 777 - Insecure permissions
:(){ :|:& };: - Fork bombs
curl | sh - Unverified script execution

Execution Modes

Manual (Default)

Commands are displayed for you to review and execute manually.

Auto-Execute

cliai auto-execute --enable

Safe commands execute automatically. Dangerous commands still require confirmation.

Dry-Run

cliai dry-run --enable

Shows what would be executed without actually running commands.

Architecture

CLIAI follows a modular architecture designed for reliability and extensibility.

Core Components

Orchestrator

Central coordinator managing AI providers and request routing.

Intent Classifier

Determines the type of request (command, question, explanation).

Context Gatherer

Collects system information for better responses.

Command Validator

Multi-layer validation with security checks.

Execution Engine

Safe command execution with multiple modes.

Performance Monitor

Tracks metrics and system health.

Circuit Breakers

Automatic failover between providers.

Request Flow

User Input
    ↓
Intent Classification
    ↓
Context Gathering
    ↓
AI Provider (Ollama/OpenAI/Anthropic)
    ↓
Command Validation
    ↓
Safety Checks
    ↓
Execution (Manual/Auto/Dry-run)

Provider Management

CLIAI uses a sophisticated provider management system:

Priority-based routing: Local first, cloud fallback
Circuit breakers: Prevent repeated failures
Retry logic: Automatic retries with backoff
Performance monitoring: Track response times
Health checks: Verify provider availability

API Documentation

For detailed Rust API documentation, see:

Rust API Docs

Key Modules

agents - AI orchestration and provider management
config - Configuration management
validation - Command validation and safety
execution - Command execution engine
providers - AI provider implementations
performance - Performance monitoring

Contributing to CLIAI

Thank you for your interest in contributing to CLIAI! We welcome contributions from the community and are excited to see what you'll bring to the project.

🚀 Getting Started

Prerequisites

Rust 1.70 or later
Git
Ollama (for testing AI functionality)

Development Setup

Fork and Clone

git clone https://github.com/yourusername/cliai.git
cd cliai

Install Dependencies
```
cargo build
```

Set up Ollama (for testing)

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a test model
ollama pull mistral

Run Tests

# Unit tests
cargo test

# Integration tests with AI
cargo run -- test --quick

🎯 How to Contribute

Reporting Issues

Use the GitHub Issues page
Search existing issues before creating a new one
Include detailed reproduction steps
Provide system information (OS, Rust version, etc.)

Suggesting Features

Open a GitHub Discussion first
Describe the use case and expected behavior
Consider implementation complexity and maintenance burden

Code Contributions

Create a Feature Branch

git checkout -b feature/your-feature-name

Make Your Changes
- Follow the existing code style
- Add tests for new functionality
- Update documentation as needed

Test Your Changes

# Run all tests
cargo test

# Test with real AI (requires Ollama)
cargo run -- test --categories "your-test-category"

# Check formatting
cargo fmt --check

# Run clippy
cargo clippy -- -D warnings

Commit Your Changes

git add .
git commit -m "feat: add amazing new feature"

Push and Create PR

git push origin feature/your-feature-name

📝 Code Style Guidelines

Rust Code Style

Use cargo fmt for consistent formatting
Follow Rust naming conventions
Add documentation comments for public APIs
Use clippy suggestions to improve code quality

Commit Messages

We follow the Conventional Commits specification:

feat: - New features
fix: - Bug fixes
docs: - Documentation changes
style: - Code style changes (formatting, etc.)
refactor: - Code refactoring
test: - Adding or updating tests
chore: - Maintenance tasks

Examples:

feat: add support for custom AI providers
fix: resolve command validation edge case
docs: update installation instructions
test: add integration tests for file operations

🏗️ Project Structure

Understanding the codebase:

src/
├── src/
│   ├── main.rs              # CLI interface and entry point
│   ├── lib.rs               # Library exports
│   ├── agents/              # AI orchestration
│   │   ├── mod.rs           # Main orchestrator
│   │   └── profiles.rs      # AI model profiles
│   ├── config.rs            # Configuration management
│   ├── context.rs           # System context gathering
│   ├── execution.rs         # Command execution
│   ├── validation.rs        # Command validation
│   ├── providers.rs         # AI provider implementations
│   ├── history.rs           # Chat history
│   ├── performance.rs       # Performance monitoring
│   ├── error_handling.rs    # Error handling
│   ├── logging.rs           # Privacy-preserving logging
│   └── test_suite.rs        # Testing framework
├── Cargo.toml               # Dependencies and metadata
├── README.md                # Project documentation
└── CONTRIBUTING.md          # This file

🧪 Testing Guidelines

Unit Tests

Write tests for all public functions
Use descriptive test names
Test both success and error cases
Mock external dependencies when possible

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_command_validation_success() {
        // Test implementation
    }
    
    #[test]
    fn test_command_validation_failure() {
        // Test implementation
    }
}
}