🤖 AIask

Turn plain English into shell commands instantly!

AIask is a powerful command-line assistant that understands what you want to do and gives you the exact shell command. No more googling syntax or reading man pages!

$ aiask "find all files larger than 100MB"

✨ Suggested command:
   find . -type f -size +100M

What would you like to do?
  [e]xecute  |  [c]opy  |  e[d]it  |  [r]e-prompt  |  [q]uit
> 

---

✨ Features

Core Features

• 🗣️ Natural Language — Just describe what you want in plain English
• 🐚 Multi-Shell — Works with PowerShell, CMD, Bash, Zsh, and Fish
• 🧠 Multiple AI Providers — Grok, OpenAI, Anthropic, Google Gemini, or local Ollama
• ⚡ Interactive — Execute, copy, edit, or refine commands before running
• 🖥️ Cross-Platform — Windows, macOS, and Linux

New in v2.0 🎉

• 📜 Command History — Track and search your command history
• 📝 Templates — Save and reuse frequently used prompts
• 🔍 Explain Mode — Understand what any command does
• 💬 Interactive REPL — Continuous conversation mode
• 🛡️ Safety Warnings — Detect and warn about dangerous commands
• ↩️ Undo Suggestions — Get undo commands after execution
• 🔧 Error Recovery — Get help when commands fail
• 📥 Stdin Support — Pipe output for analysis
• 🎨 Syntax Highlighting — Colorized command output
• 🌍 Environment Variables — Configure via env vars for CI/CD
• 📤 JSON Output — Machine-readable output for scripting
• 🐛 Verbose Mode — Debug information when needed
• ⏱️ Configurable Timeout — Adjust request timeouts
• 🔄 Auto-Update Check — Know when updates are available
• 🎯 Shell Completions — Tab completion for Bash, Zsh, Fish, PowerShell

---

📦 Installation

🪟 Windows

Option 1: winget

winget install Hermithic.aiask

Option 2: Direct download

# Download the latest release
Invoke-WebRequest -Uri "https://github.com/Hermithic/aiask/releases/latest/download/aiask-2.0.1-windows-amd64.zip" -OutFile aiask.zip
Expand-Archive aiask.zip -DestinationPath .
Move-Item aiask-windows-amd64.exe C:\Windows\aiask.exe

🍎 macOS

brew tap Hermithic/aiask
brew install aiask

🐧 Linux

Option 1: Direct binary (Recommended)

wget https://github.com/Hermithic/aiask/releases/latest/download/aiask-2.0.1-linux-amd64.tar.gz
tar -xzf aiask-2.0.1-linux-amd64.tar.gz
sudo mv aiask-linux-amd64 /usr/local/bin/aiask

Option 2: One-liner install

curl -fsSL https://raw.githubusercontent.com/Hermithic/aiask/master/install.sh | bash

🔧 From Source

Requires Go 1.23+:

git clone https://github.com/Hermithic/aiask.git
cd aiask
go build -o aiask ./cmd/aiask

---

⚙️ Configuration

Quick Setup

aiask config

This interactive wizard helps you configure your AI provider.

Supported Providers

Provider	Description	API Key Required
🚀 Grok	xAI's Grok (recommended)	Yes
🤖 OpenAI	GPT-4o, GPT-4	Yes
🧠 Anthropic	Claude 3.5/4	Yes
✨ Gemini	Google Gemini	Yes
🏠 Ollama	Run locally, free!	No

🔑 Getting API Keys

Provider	Where to get it
Grok	console.x.ai
OpenAI	platform.openai.com
Anthropic	console.anthropic.com
Gemini	ai.google.dev
Ollama	No key needed! ollama.ai

📁 Configuration File

AIask stores your settings in ~/.aiask/config.yaml:

provider: grok
api_key: "xai-..."
model: "grok-3"
timeout: 60                    # Request timeout in seconds
ollama_url: "http://localhost:11434"
system_prompt_suffix: ""       # Custom instructions for the AI
check_updates: true            # Check for updates on startup

🌍 Environment Variables

Configure AIask without a config file (great for CI/CD):

export AIASK_PROVIDER=openai
export AIASK_API_KEY=sk-...
export AIASK_MODEL=gpt-4o
export AIASK_TIMEOUT=120
export AIASK_OLLAMA_URL=http://localhost:11434
export AIASK_SYSTEM_PROMPT_SUFFIX="Prefer one-liners when possible"

Environment variables take precedence over the config file.

🏠 Using Ollama (100% Local & Free)

For maximum privacy, run AI completely locally:

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

# 2. Pull a model
ollama pull llama3.2

# 3. Configure AIask
aiask config  # Select "ollama"

---

🚀 Usage

Basic Usage

aiask "your request in plain English"

📚 Examples

File Operations:

aiask "list all .txt files modified in the last 7 days"
aiask "find and delete all empty directories"
aiask "compress the logs folder into a zip"
aiask "count lines of code in all Python files"

System Info:

aiask "show disk usage for each partition"
aiask "list all running processes sorted by memory"
aiask "what's my public IP address"
aiask "show system uptime"

Git Operations:

aiask "undo my last commit but keep the changes"
aiask "show commits from the last week"
aiask "create a new branch called feature-login"
aiask "squash the last 3 commits"

Networking:

aiask "list all open ports"
aiask "download this file from URL"
aiask "check if google.com is reachable"
aiask "show my network interfaces"

⌨️ Interactive Options

After AIask suggests a command:

Key	Action
e	▶️ Execute — Run the command now
c	📋 Copy — Copy to clipboard
d	✏️ Edit — Modify before running
r	🔄 Re-prompt — Ask something different
q	👋 Quit — Exit without action

---

🆕 New Features in v2.0

🔍 Explain Mode

Understand what any command does:

aiask explain "tar -xzvf archive.tar.gz"
aiask explain "git rebase -i HEAD~3"
aiask explain "find . -name '*.log' -mtime +7 -delete"

📜 Command History

Track and search your command history:

aiask history              # Show recent history
aiask history -n 20        # Show last 20 entries
aiask history --search git # Search history
aiask history clear        # Clear all history

📝 Templates

Save and reuse frequently used prompts:

# Save a template
aiask save git-log "show commits from the last week with stats"
aiask save find-large "find files larger than 100MB" -d "Find large files"

# List templates
aiask templates

# Run a template
aiask run git-log

💬 Interactive REPL Mode

Continuous conversation mode without restarting:

aiask interactive
# or
aiask i

Commands in REPL:

• /help — Show available commands
• /history — Show session history
• /config — Show current configuration
• /clear — Clear the screen
• /exit — Exit interactive mode

📥 Stdin Support

Pipe output for analysis:

# Analyze error logs
cat error.log | aiask --stdin "what's wrong here?"

# Get help with failed commands
npm install 2>&1 | aiask --stdin "how do I fix this?"

# Analyze any output
docker logs myapp | aiask --stdin "find any errors"

🛡️ Safety Features

AIask automatically warns about dangerous commands:

$ aiask "delete all files in root"

⚠️  CRITICAL Warning
   • Recursive delete of root, all files, or home directory

   Type 'yes' to confirm execution, or any other key to cancel.

After execution, get undo suggestions:

💡 To undo: git reset HEAD~1
   (Undo the last commit, keeps changes staged)

📤 JSON Output

Machine-readable output for scripting:

aiask --json "list files" | jq .command

Output:

{
  "command": "ls -la",
  "shell": "bash",
  "os": "linux",
  "prompt": "list files",
  "provider": "grok",
  "model": "grok-3"
}

🐛 Verbose Mode

Debug information when needed:

aiask -v "show disk space"

Output:

[DEBUG] Shell: PowerShell
[DEBUG] OS: Windows
[DEBUG] Provider: grok
[DEBUG] Model: grok-3
[DEBUG] Timeout: 1m0s
[DEBUG] Prompt: show disk space
[DEBUG] Response time: 1.234s

🎯 Shell Completions

Enable tab completion for your shell:

# Bash
aiask completion bash > /etc/bash_completion.d/aiask

# Zsh
aiask completion zsh > "${fpath[1]}/_aiask"

# Fish
aiask completion fish > ~/.config/fish/completions/aiask.fish

# PowerShell
aiask completion powershell | Out-String | Invoke-Expression

---

🤖 Supported Models

Provider	Default	Other Options
Grok	grok-3	grok-2
OpenAI	gpt-4o	gpt-4o-mini, gpt-4-turbo
Anthropic	claude-sonnet-4-20250514	claude-3-opus
Gemini	gemini-2.0-flash	gemini-1.5-pro
Ollama	llama3.2	mistral, codellama, phi

---

🐚 Shell Detection

AIask automatically detects your shell and generates appropriate commands:

Platform	Shells Detected
Windows	PowerShell, CMD
macOS/Linux	Bash, Zsh, Fish

It also detects:

• Current working directory
• Git repository status (branch, dirty state)

---

📋 Command Reference

Usage:
  aiask [prompt] [flags]
  aiask [command]

Available Commands:
  config      Configure aiask settings
  explain     Explain what a command does
  history     View command history
  interactive Start interactive REPL mode
  templates   Manage saved prompt templates
  save        Save a new template
  run         Run a saved template
  completion  Generate shell completion scripts
  version     Print the version number
  help        Help about any command

Flags:
  -v, --verbose   Show verbose output including debug information
      --json      Output result as JSON (non-interactive)
      --stdin     Read additional context from stdin
  -s, --stream    Stream the response as it generates
  -h, --help      Help for aiask

---

🔨 Building from Source

Prerequisites

• Go 1.23+
• Make (optional)

Build Commands

make build        # Build for current platform
make build-all    # Build for all platforms
make release      # Create release archives
make deb          # Build .deb package
make checksums    # Generate SHA256 checksums

Cross-Compilation

# Windows
GOOS=windows GOARCH=amd64 go build -o aiask.exe ./cmd/aiask

# Linux
GOOS=linux GOARCH=amd64 go build -o aiask ./cmd/aiask

# macOS
GOOS=darwin GOARCH=arm64 go build -o aiask ./cmd/aiask

---

🔧 Troubleshooting

❌ "Config not found" Error

aiask config  # Run the setup wizard

Or set environment variables:

export AIASK_PROVIDER=openai
export AIASK_API_KEY=sk-...

❌ API Errors

1. ✅ Verify your API key is correct
2. ✅ Check you have credits/quota with your provider
3. ✅ Ensure you're using a valid model name
4. ✅ Try increasing the timeout: export AIASK_TIMEOUT=120

❌ Ollama Connection Issues

ollama serve    # Make sure Ollama is running
ollama list     # Verify you have models installed

❌ Command Not Executing

Some commands need elevated privileges:

• Windows: Run terminal as Administrator
• Linux/macOS: Use sudo

❌ Slow Responses

Try a faster model:

# In ~/.aiask/config.yaml
model: gpt-4o-mini  # Faster than gpt-4o

---

🔒 Privacy & Security

• 🔐 API keys stored locally in ~/.aiask/config.yaml with restricted permissions
• 📤 Prompts are sent to your configured AI provider
• 🏠 Use Ollama for 100% local, private inference
• ✋ Commands never execute without your confirmation
• 🛡️ Dangerous commands require explicit "yes" confirmation
• 📜 History stored locally in ~/.aiask/history.yaml

---

🤝 Contributing

Contributions are welcome! Feel free to:

• 🐛 Report bugs
• 💡 Suggest features
• 🔧 Submit pull requests

---

📄 License

MIT License — see LICENSE for details.

---

📝 Changelog

v2.0.1 (2025-11-26)

• 🔧 Fixed release artifacts and distribution package configurations
• 🔧 Updated Homebrew formula with correct checksums
• 🔧 Fixed winget manifest structure for package submission

v2.0.0 (2025-11-26)

• ✨ Added explain command to describe what commands do
• ✨ Added command history with search (aiask history)
• ✨ Added templates system (aiask save, aiask run, aiask templates)
• ✨ Added interactive REPL mode (aiask interactive)
• ✨ Added stdin support for piping input (--stdin)
• ✨ Added JSON output mode (--json)
• ✨ Added verbose/debug mode (-v)
• ✨ Added dangerous command detection and warnings
• ✨ Added undo suggestions after command execution
• ✨ Added error recovery assistance
• ✨ Added shell completion scripts (aiask completion)
• ✨ Added environment variable configuration
• ✨ Added configurable timeout
• ✨ Added custom system prompt suffix
• ✨ Added auto-update check on startup
• ✨ Added git context awareness (branch, dirty status)
• ✨ Added directory context in prompts
• ✨ Added syntax highlighting for commands
• 🐛 Fixed various shell detection issues
• 📚 Comprehensive documentation update

v1.0.0 (2025-01-15)

• 🎉 Initial release
• Basic natural language to command conversion
• Support for multiple AI providers
• Cross-platform support

---

Made with ❤️ by Hermithic