BeginnerAIChatRustCLILLMOpenAIClaudeGeminiOllamaRAGShell AssistantREPLAI Agents

AIChat: All-in-One LLM CLI Tool Setup

Complete setup guide for AIChat - an all-in-one LLM CLI tool featuring Shell Assistant, Chat-REPL, RAG, AI Tools & Agents. Written in Rust, supporting 20+ LLM providers including OpenAI, Claude, Gemini, and Ollama. Includes installation, configuration, and usage examples for command-line AI workflows.

Step 1
System Prerequisites
AIChat is a Rust-based CLI tool that runs on macOS, Linux, and Windows. Before installation, verify you have a compatible environment. No specific system requirements are listed, but you'll need network connectivity to access LLM APIs and sufficient disk space for the binary (~5-10MB).
```
# Check your OS and shell
uname -a
echo $SHELL

# If installing via cargo, check Rust version
rustc --version  # Rust 1.70+ recommended
```
Step 2
Installation via Package Manager (Recommended)
AIChat is available through multiple package managers, making installation straightforward. Choose the method that matches your system. The package manager approach ensures automatic dependency resolution and easy updates.
```
# Rust developers (all platforms)
cargo install aichat

# Homebrew/Linuxbrew (macOS/Linux)
brew install aichat

# Arch Linux
sudo pacman -S aichat

# Windows Scoop
scoop install aichat

# Android Termux
pkg install aichat
```
Step 3
Installation via Pre-built Binary
For systems without a package manager, download pre-built binaries from GitHub Releases. This method works on any platform and doesn't require Rust toolchain installation.
```
# Download latest release (Linux example)
wget https://github.com/sigoden/aichat/releases/latest/download/aichat-vX.Y.Z-x86_64-unknown-linux-musl.tar.gz

# Extract binary
tar -xzf aichat-*.tar.gz

# Move to PATH
sudo mv aichat /usr/local/bin/

# Verify installation
aichat --version
```
⚠ Heads up: Replace X.Y.Z with the actual version number from the releases page. For macOS, use the darwin binary. For Windows, download the .exe file.

Step 4

First Run and Configuration

On first launch, AIChat generates a configuration file and prompts you to select an LLM provider and provide credentials. The configuration file location varies by OS and stores all your settings, API keys, and preferences.

# First run - will trigger interactive setup
aichat

# Check configuration file location
aichat --info | grep config_file

# Configuration file locations by OS:
# Linux:   ~/.config/aichat/config.yaml
# macOS:   ~/Library/Application Support/aichat/config.yaml
# Windows: %APPDATA%\aichat\config.yaml

Step 5
Configure LLM Provider via Environment Variables
The quickest way to get started is using environment variables for API keys. AIChat supports 20+ providers including OpenAI, Claude (Anthropic), Google Gemini, Ollama, Groq, and more. Choose your preferred provider and set the corresponding API key.
```
# OpenAI setup
export OPENAI_API_KEY=sk-your-openai-key-here
export AICHAT_PLATFORM=openai

# Claude (Anthropic) setup
export ANTHROPIC_API_KEY=sk-ant-your-anthropic-key
export AICHAT_PLATFORM=claude

# Google Gemini setup
export GEMINI_API_KEY=your-gemini-api-key
export AICHAT_PLATFORM=gemini

# Ollama (local, no API key needed)
export AICHAT_PLATFORM=ollama

# Test the configuration
aichat "Hello, world!"
```
⚠ Heads up: API keys are sensitive credentials. Never commit them to version control. For persistent setup, add these exports to your ~/.bashrc, ~/.zshrc, or ~/.profile file.

Step 6

Configure Specific Model

By default, AIChat uses the first available chat model for your selected platform. You can specify exact models using the AICHAT_MODEL environment variable or in the configuration file. Each provider offers different models with varying capabilities and costs.

# Set specific OpenAI model
export AICHAT_MODEL=openai:gpt-4o

# Set Claude model
export AICHAT_MODEL=claude:claude-sonnet-4-5

# Set Gemini model
export AICHAT_MODEL=gemini:gemini-2.0-flash-exp

# Set Ollama local model
export AICHAT_MODEL=ollama:llama3.2

# Verify current configuration
aichat --info

Step 7

Edit Configuration File Directly

For advanced configuration including temperature, top_p, streaming, and multi-provider setups, edit the YAML configuration file directly. The file is well-documented with inline comments explaining each setting.

# Open config in default editor
aichat --edit-config

# Or edit directly
nano ~/.config/aichat/config.yaml

# Example configuration snippet:
# model: openai:gpt-4o
# temperature: 0.7
# top_p: 0.9
# stream: true
# keybindings: emacs
# clients:
#   - type: openai
#     api_key: sk-xxx

Step 8
Using Shell Assistant Mode
Shell Assistant is one of AIChat's most powerful features - it converts natural language descriptions into precise shell commands adapted to your OS and shell environment. Perfect for complex command construction and discovering command options.
```
# Basic shell command generation
aichat -e "find all json files larger than 10MB"

# The -e flag executes the generated command
aichat -e "compress all log files in /var/log older than 7 days"

# Without -e, just shows the command (safe preview)
aichat "list all docker containers with their memory usage"

# Complex multi-step commands
aichat -e "backup my home directory excluding node_modules to /backup"
```
⚠ Heads up: Always review generated commands before executing with -e flag. Start without -e to preview the command, especially for destructive operations like rm or dd.

Step 9

Using Chat-REPL Mode

Chat-REPL provides an interactive environment for sustained conversations with your LLM. It features tab completion, multi-line input, history search (Ctrl+R), and persistent sessions. This is ideal for complex reasoning tasks, coding assistance, and iterative problem solving.

# Start interactive REPL
aichat

# Within REPL, special commands start with .
.help          # Show all REPL commands
.info          # Show current configuration
.model gpt-4o  # Switch models mid-session
.role          # Set a custom role
.session       # Create/manage sessions
.file image.png # Attach files to messages
.edit          # Open multi-line editor
.exit          # Exit REPL

Step 10

Working with Files and Input Sources

AIChat accepts multiple input types: stdin, local files, directories, remote URLs, and command output. You can combine multiple sources in a single query for rich contextual prompts.

# Analyze a single file
aichat -f document.pdf "Summarize this document"

# Process an image
aichat -f screenshot.png "What does this error mean?"

# Analyze entire directory
aichat -f ./src "Review this code for security issues"

# Fetch and analyze URL
aichat -f https://example.com/api/docs "Explain this API"

# Combine multiple sources
aichat -f code.py -f tests.py "Are these tests comprehensive?"

# Pipe command output
ls -la | aichat "Explain the largest files"

Step 11

Using Roles for Specialized Tasks

Roles customize LLM behavior for specific use cases, enhancing interaction efficiency. AIChat supports predefined roles and custom role creation. Roles can include instructions, temperature settings, and default context.

# List available roles
aichat --list-roles

# Use a specific role
aichat --role coder "Write a Python function to parse JSON"

# In REPL, switch roles
.role coder

# Create custom role (edit roles.yaml)
aichat --edit-roles

# Example custom role definition:
# - name: reviewer
#   prompt: You are a code reviewer. Focus on bugs and security.
#   temperature: 0.3

Step 12

Session Management

Sessions maintain conversation context across multiple interactions, enabling continuous, context-aware conversations. This is essential for complex projects requiring sustained context.

# Start a new session
aichat --session debug-session

# Within REPL, manage sessions
.session                    # List sessions
.session new project-x      # Create session
.session save               # Save current
.session load project-x     # Load session

# Sessions are auto-saved and persisted
# Location: ~/.config/aichat/sessions/

Step 13
RAG (Retrieval-Augmented Generation) Setup
RAG integrates external documents into conversations for contextually relevant responses. AIChat can index local files, directories, and URLs, then query them during chat. This is perfect for working with documentation, codebases, or knowledge bases.
```
# Create RAG from local directory
aichat --rag-create docs ./documentation/

# Create RAG from URL
aichat --rag-create wiki https://github.com/user/repo/wiki/**

# Query with RAG context
aichat --rag docs "How do I configure authentication?"

# In REPL, use RAG
.rag docs
# Now all queries use the docs context

# List available RAGs
aichat --list-rags
```
⚠ Heads up: RAG requires an embedding model. Configure embedding settings in config.yaml. OpenAI embeddings work out-of-box. For local embeddings, use Ollama with models like nomic-embed-text.

Step 14

Creating AI Agents

AI Agents are the CLI equivalent of OpenAI GPTs - reusable assistants combining custom instructions, tools, and documents. Agents are configured via YAML files and can be invoked by name.

# List available agents
aichat --list-agents

# Use an agent
aichat --agent coder "Write a REST API handler"

# Create new agent directory
mkdir -p ~/.config/aichat/agents/my-agent

# Create agent config
cat > ~/.config/aichat/agents/my-agent/config.yaml << 'EOF'
name: my-agent
instructions: You are a helpful assistant specializing in DevOps
model: gpt-4o
temperature: 0.7
tools:
  - name: shell
EOF

# Use your custom agent
aichat --agent my-agent "Deploy to production"

Step 15

Local Server Mode

AIChat can run as an HTTP server providing OpenAI-compatible APIs for Chat Completions, Embeddings, and Rerank endpoints. It also includes a web-based LLM Playground and Arena for testing and comparing models.

# Start server on default port 8080
aichat --serve

# Custom port
aichat --serve 0.0.0.0:3000

# Test Chat Completions API
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# Access web playground
# Open http://localhost:8080 in browser

Step 16

Advanced Configuration Options

Fine-tune AIChat behavior with advanced settings including proxies, custom model definitions, request patching, and appearance customization. These settings live in config.yaml.

# Proxy configuration (add to config.yaml)
clients:
  - type: openai
    api_key: sk-xxx
    proxy: socks5://127.0.0.1:1080

# Custom theme
light_theme: true
highlight: true

# Keybindings (emacs or vi)
keybindings: emacs

# Streaming and saving
stream: true
save: true

# Text wrapping
wrap: auto

# External editor
editor: vim

Step 17

Common Usage Patterns

Practical examples combining AIChat features for real-world workflows. These patterns demonstrate how to leverage AIChat for daily development, operations, and research tasks.

# Code review workflow
aichat --role reviewer -f src/ "Review for security issues"

# Debug with context
aichat --session debug -f error.log -f app.py "Why is this failing?"

# Documentation query with RAG
aichat --rag docs "Show me examples of authentication"

# Generate and execute shell command
aichat -e "backup database to S3 with timestamp"

# Multi-modal analysis
aichat -f screenshot.png -f code.js "Does this UI match the code?"

# Agent-based automation
aichat --agent devops "Check server health and report issues"

Step 18

Updating AIChat

Keep AIChat up-to-date to access new features, model support, and bug fixes. Update methods mirror installation methods.

# Update via cargo
cargo install aichat --force

# Update via Homebrew
brew upgrade aichat

# Update via pacman
sudo pacman -Syu aichat

# Check current version
aichat --version

# View changelog
aichat --info

Step 19
Troubleshooting Common Issues
Solutions to common problems when setting up or using AIChat. Most issues stem from API key configuration, network connectivity, or model availability.
```
# Verify configuration
aichat --info

# Test API connectivity
aichat "test" --verbose

# Check API key validity
echo $OPENAI_API_KEY  # Should show key

# Reset configuration
rm ~/.config/aichat/config.yaml
aichat  # Will regenerate config

# View detailed error messages
aichat --verbose "your query"

# Check logs (if enabled)
tail -f ~/.config/aichat/aichat.log
```
⚠ Heads up: If Ollama models fail, ensure Ollama server is running (ollama serve) and models are pulled (ollama pull llama3.2). For cloud providers, verify API key permissions and account credit balance.

AIChat: All-in-One LLM CLI Tool Setup

System Prerequisites

Installation via Package Manager (Recommended)

Installation via Pre-built Binary

First Run and Configuration

Configure LLM Provider via Environment Variables

Configure Specific Model

Edit Configuration File Directly

Using Shell Assistant Mode

Using Chat-REPL Mode

Working with Files and Input Sources

Using Roles for Specialized Tasks

Session Management

RAG (Retrieval-Augmented Generation) Setup

Creating AI Agents

Local Server Mode

Advanced Configuration Options

Common Usage Patterns

Updating AIChat

Troubleshooting Common Issues

Feature requests

Discussion