Skip to content

Getting Started

Installation

Welcome to the last manual installation you'll ever need. In the future you'll just be able to do wtf install X.

Take your time. Read through and debate the 3 different options. Reminice on the changing of an era.

The installation script handles everything, including collision detection:

curl -sSL https://raw.githubusercontent.com/davefowler/wtf-terminal-ai/main/install.sh | bash

This will:

  • Check for Python 3.9+
  • Install wtf-ai via pip
  • Detect if you already have a wtf alias/command
  • Offer alternative names (wtfai, wai) if collision detected
  • Set up PATH if needed

Option 2: pip

pip install git+https://github.com/davefowler/wtf-terminal-ai.git

Simple. Direct. No frills. Just like we like our coffee.

Option 3: From Source

For the brave souls who like living on the edge:

git clone https://github.com/davefowler/wtf-terminal-ai.git
cd wtf-terminal-ai
pip install -e .

First Run

On first use, wtf automatically runs a setup wizard:

$ wtf "help me"

⚠  No configuration found. Running setup wizard...

Welcome to wtf setup!

Let's get you configured. This will only take a moment.

Step 1: Choose your AI provider

  1. Anthropic (Claude)
  2. OpenAI (GPT)
  3. Google (Gemini)

Select provider [1]: _

Choose Your Provider

Anthropic Claude (Recommended) - Best at understanding context - Most "Gilfoyle-like" responses - Get key: https://console.anthropic.com/settings/keys

OpenAI GPT - Fastest responses - Most widely available - Get key: https://platform.openai.com/api-keys

Google Gemini - Good multimodal support - Free tier available - Get key: https://makersuite.google.com/app/apikey

Local Models (Ollama) - No API key needed! - 100% private - runs on your machine - Free forever - Works offline - Install: https://ollama.ai

# Install Ollama, then pull a model
ollama pull llama3.2

# wtf will auto-detect it
wtf --setup

API Key Setup

You can store your API key in two ways:

Environment Variable (Recommended) 

export ANTHROPIC_API_KEY='your-key-here'
export OPENAI_API_KEY='your-key-here'
export GOOGLE_API_KEY='your-key-here'

Add to your ~/.zshrc or ~/.bashrc to persist.

Config File The wizard can store it in ~/.config/wtf/config.json for you.

Warning

Config file storage is convenient but less secure. Use environment variables in production.

Model Selection

Each provider offers multiple models:

Anthropic: - claude-opus-4 (Recommended) - Most capable, flagship model - claude-sonnet-4 - Great balance of performance and speed - claude-3-5-haiku-latest - Fastest, cheapest

OpenAI: - gpt-4o (Recommended) - Great balance of speed and capability - gpt-4o-mini - Faster, cheaper - o1 / o3 - Advanced reasoning models - gpt-4.1 / gpt-5 - Latest generation

Google: - gemini-2.5-pro (Recommended) - Most capable - gemini-2.5-flash - Fast and efficient - gemini-2.0-flash - Previous generation

Local (Ollama) - Free, Private: - llama3.2 - Latest Llama, great all-around - llama3.1 / llama3 - Previous Llama versions - mistral - Fast and capable - qwen2.5 - Strong multilingual support - deepseek-r1 - Advanced reasoning - codellama - Optimized for code

Verify Installation

wtf --version
# wtf 0.x.0

wtf "hello"
# [AI responds with personality]

Shell Integration (Important!)

To use wtf without quotes around every query, add this to your ~/.zshrc or ~/.bashrc:

alias wtf='noglob wtf'

Then restart your shell: source ~/.zshrc

Why? Without this, zsh/bash will try to expand ? and * as glob patterns:

# Without alias - ERROR
wtf are you there?
# zsh: no matches found: there?

# With alias - WORKS
wtf are you there?
# [AI responds]

# Always works with quotes
wtf "are you there?"
# [AI responds]

The curl installation script adds this alias automatically.

Next Steps

Troubleshooting

wtf: command not found

Your PATH doesn't include the pip installation directory. Add this to ~/.zshrc or ~/.bashrc:

export PATH="$PATH:$HOME/.local/bin"

Then: source ~/.zshrc

API key errors

Make sure your API key is set:

echo $ANTHROPIC_API_KEY  # Should print your key

If empty, set it in your shell config or run: wtf --setup

Python version issues

wtf requires Python 3.9+. Check your version:

python3 --version

If too old, install a newer Python:

# macOS
brew install python3

# Ubuntu
sudo apt install python3.11

# Fedora
sudo dnf install python3.11