WTF CLI - AI Assisted Terminal

A transparent PTY-based terminal wrapper with AI-powered assistance. Get instant explanations for errors, suggestions for fixes, and interactive chat with an AI that sees your terminal context.

🚀 Getting Started

Prerequisites

• Go 1.24+
• Linux or macOS
• OpenRouter API key (for AI features)

Installation

Quick Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/pakru/wtf_cli/main/install.sh | bash

This will automatically detect your platform, download the latest release, verify checksums, and install to the appropriate location.

Option 1: Download Pre-built Binary

Download the latest release for your platform from the Releases page:

# Linux/macOS example
wget https://github.com/pakru/wtf_cli/releases/latest/download/wtf_cli_<version>_<os>_<arch>.tar.gz
tar -xzf wtf_cli_<version>_<os>_<arch>.tar.gz
chmod +x wtf_cli
./wtf_cli --version

# Optionally install to PATH
sudo mv wtf_cli /usr/local/bin/

Option 2: Build from Source

# Clone the repository
git clone https://github.com/pakru/wtf_cli.git
cd wtf_cli

# Build
make build

# Run
./wtf_cli

Usage

# Check version
./wtf_cli --version

# Start the wrapper
./wtf_cli

# Use your terminal normally
ls -la
cd ~/projects

# Press / at an empty prompt to open command palette
# Select a command with arrow keys and Enter

# Press Ctrl+R to search command history
# Type to filter, use Up/Down/Tab to select

# Press Ctrl+T to toggle the AI chat sidebar
# Type questions and get context-aware responses

✨ Features

Commands (Available)

Command	Description
/chat	Toggle AI chat sidebar
/explain	Analyze last output and suggest fixes
/history	Show command history
/settings	Open settings panel
/help	Show help

Keyboard Shortcuts

Shortcut	Action
Ctrl+D	Exit terminal (press twice)
Ctrl+C	Cancel current command
Ctrl+Z	Suspend process
Ctrl+R	Search command history
Ctrl+T	Toggle AI chat sidebar
/	Open command palette (at empty prompt)
Esc	Close palette/panel/sidebar
←/→	Move cursor in command line
Home/End	Jump to start/end of command line

Tech Stack

• Go - Core language
• creack/pty - Pseudo-terminal management
• Bubble Tea - TUI framework
• Lipgloss - Styling
• OpenRouter API - LLM integration (supports 400+ models)

🧪 Development

Available Make Targets

# Run all checks, build, and test (default)
make all

# Build the binary
make build

# Run all tests
make test

# Format all Go code
make fmt

# Run static analysis
make vet

# Run formatting and vetting
make lint

# Full pre-commit validation (fmt, vet, build, test)
make check

# Clean build artifacts
make clean

# Build and run the application
make run

# Show help with all available targets
make help

# Run directly without make
go run cmd/wtf_cli/main.go

Code Quality

Before committing, run:

make check

This will automatically:

1. Format your code with go fmt
2. Run go vet for static analysis
3. Build the project
4. Run all tests

🔧 Troubleshooting

Go Version Mismatch Error

If you see an error like:

compile: version "go1.25.0" does not match go tool version "go1.25.5"

This happens when Go is updated but cached packages are from an older version. Fix it with:

# Clear all caches and reinstall standard library
rm -rf ~/.cache/go-build
go clean -cache -modcache -i -r
go install std

# Rebuild the project
make clean
make build

🚀 Release Process

For maintainers: See docs/RELEASE.md for detailed release instructions.

Quick Release:

# Commit your changes
git add .
git commit -m "Your changes"

# Create and push tag (version comes from the tag)
git tag v0.4.0
git push origin main --tags

# GitHub Actions will automatically build and create the release

📝 Configuration

Configuration file: ~/.wtf_cli/config.json

{
  "llm_provider": "openrouter",
  "openrouter": {
    "api_key": "<your_api_key>",
    "model": "google/gemini-2.0-flash-exp:free",
    "temperature": 0.7,
    "max_tokens": 2000,
    "api_timeout_seconds": 30
  },
  "buffer_size": 2000,
  "context_window": 1000,
  "status_bar": {
    "position": "bottom"
  }
}

🤝 Contributing

Contributions are welcome! Please read the contribution guidelines first.

📄 License

MIT License - see LICENSE for details.