FAQ

Common questions and answers about Rawi usage, configuration, and troubleshooting.

General Questions

What is Rawi?

Rawi is a powerful command-line interface (CLI) tool that brings AI assistance directly to your terminal. It allows you to interact with various AI providers (OpenAI, Anthropic, Google, DeepSeek, Mistral, Cerebras, etc.) to help with coding, writing, analysis, and many other tasks.

How is Rawi different from other AI tools?

• Terminal-native: Works directly in your command line
• Multiple providers: Support for OpenAI, Anthropic, Google, DeepSeek, Mistral, Cerebras, Ollama, LM Studio, Azure, Bedrock, Qwen, and xAI
• Session management: Maintain conversation context across commands
• Act templates: Pre-built prompts for specific tasks
• Shell integration: Pipe data in/out of other commands
• Profile support: Different configurations for different use cases

Is Rawi free to use?

Rawi itself is free and open-source. However, you’ll need API access to AI providers:

• Free options: Ollama (local), some providers offer free tiers
• Paid options: OpenAI, Anthropic, Google (pay per usage)
• Cost: Typically cents per request for most use cases

---

Installation and Setup

What are the system requirements?

• Node.js: Version 18 or higher
• Operating System: Windows, macOS, or Linux
• Internet: Required for cloud AI providers (not needed for local providers like Ollama)
• API Keys: Required for cloud providers

How do I install Rawi?

# Install globally via npm
npm install -g rawi

# Or using other package managers
yarn global add rawi
pnpm add -g rawi
bun add -g rawi

# Use without installing (npx)
npx rawi ask "What is TypeScript?"

How do I get started after installation?

# Run interactive configuration
rawi configure

# Check your setup
rawi info

# Ask your first question
rawi ask "Hello, how can you help me?"

How do I get API keys for different providers?

OpenAI:

1. Visit platform.openai.com
2. Sign up or log in
3. Go to API Keys section
4. Create new secret key

Anthropic:

1. Visit console.anthropic.com
2. Sign up or log in
3. Go to API Keys
4. Generate new key

Google:

1. Visit Google AI Studio
2. Sign in with Google account
3. Get API key from settings

Ollama (Local):

1. Install from ollama.ai
2. Run ollama pull llama2 (or other models)
3. No API key needed

---

Usage Questions

How do I ask questions effectively?

1. Be specific and provide context:

   # Good
   rawi ask "How do I handle async/await errors in JavaScript when making API calls?"
   
   # Too vague
   rawi ask "Help with JavaScript"

2. Include relevant information:

   rawi ask "In a React TypeScript app, how do I handle form validation with Formik?"

3. Use act templates for specialized help:

   rawi ask --act code-reviewer "Review this Python function for improvements"

What are act templates?

Act templates are pre-built prompts that transform your AI into specialized experts:

# List all templates
rawi act --list

# Get template details
rawi act --show software-engineer

# Use a template
rawi ask --act code-reviewer "Review this code for issues"

Popular templates include:

• software-engineer — General development help
• code-reviewer — Code analysis and improvements
• technical-writer — Documentation assistance
• debugging-expert — Help with bugs and errors

How do sessions work?

Sessions maintain conversation context across multiple interactions:

# Start a new session
rawi ask --new-session "I'm building a REST API in Node.js"

# Continue the conversation (remembers context)
rawi ask "How do I add authentication?"
rawi ask "What about rate limiting?"

# List your sessions
rawi history --sessions

# Continue a specific session
rawi ask --session abc123 "Let's continue our API discussion"

How do I use profiles?

Profiles store different configurations for different use cases:

# Create profiles
rawi configure --profile work --provider openai --model gpt-4
rawi configure --profile personal --provider anthropic --model claude-3-5-sonnet

# Use profiles
rawi ask --profile work "Help me with this enterprise code"
rawi ask --profile personal "Write a creative story"

# List profiles
rawi configure --list

---

Configuration Questions

How do I switch between AI providers?

# Configure different providers
rawi configure --provider openai --api-key sk-your-key
rawi configure --provider anthropic --api-key sk-ant-your-key

# Use specific profile
rawi ask --profile openai-profile "Your question"

# Change default provider
rawi configure --provider anthropic --set-default

Can I use multiple models?

Yes! You can configure different profiles with different models:

# Fast/cheap model for quick questions
rawi configure --profile quick --provider openai --model gpt-3.5-turbo

# Powerful model for complex tasks
rawi configure --profile powerful --provider openai --model gpt-4

# Local model for privacy
rawi configure --profile private --provider ollama --model llama2

How do I configure environment variables?

# Set API keys as environment variables
export OPENAI_API_KEY="sk-your-key"
export ANTHROPIC_API_KEY="sk-ant-your-key"

# Default profile
export RAWI_PROFILE="work"

# Add to your shell config (.bashrc, .zshrc)
echo 'export OPENAI_API_KEY="sk-your-key"' >> ~/.bashrc

Where are configuration files stored?

• Linux/macOS: ~/.config/rawi/
• Windows: %APPDATA%/rawi/

Files include:

• config.json — Main configuration
• profiles/ — Profile configurations
• history/ — Session history

---

Shell Integration

How do I pipe data to Rawi?

# Analyze files
cat app.js | rawi ask --act code-reviewer "Review this code"

# Process command output
ps aux | rawi ask "Which processes are using the most memory?"

# Analyze logs
tail -f app.log | rawi ask "Monitor for any critical errors"

# Git integration
git diff | rawi ask "Summarize these changes"

How do I save Rawi output?

# Save to file
rawi ask "Explain Docker containers" > docker-notes.txt

# Append to file
rawi ask "More Docker info" >> docker-notes.txt

# Pipe to other commands
rawi ask "Generate JSON data" | jq '.'

Can I use Rawi in scripts?

Yes! Rawi works great in automation scripts:

#!/bin/bash
# Code review script
for file in src/*.js; do
    echo "Reviewing $file..."
    cat "$file" | rawi ask --act code-reviewer "Quick review" > "reviews/$(basename "$file").md"
done

---

Troubleshooting

”Command not found: rawi”

Cause: Rawi not installed or not in PATH

Solutions:

# Reinstall globally
npm install -g rawi

# Check installation
npm list -g rawi

# Use npx if global install fails
npx rawi ask "test"

“No provider configured”

Cause: No AI provider set up

Solution:

# Run interactive configuration
rawi configure

# Or configure manually
rawi configure --provider openai --api-key sk-your-key

“API key not found” or “Authentication failed”

Cause: Invalid or missing API key

Solutions:

# Check current configuration
rawi configure --show

# Update API key
rawi configure --provider openai --api-key sk-your-new-key

# Verify with environment variable
export OPENAI_API_KEY="sk-your-key"
rawi info

“Request failed” or “Network error”

Possible causes and solutions:

1. Internet connection: Check your network
2. API limits: Wait and try again, or upgrade your plan
3. Invalid model: Check available models with rawi provider --models openai
4. Provider outage: Try a different provider or wait

# Test with different provider
rawi configure --provider anthropic
rawi ask "test connection"

# Check API status
curl -s https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"

Sessions not working properly

Solutions:

# List sessions to check IDs
rawi history --sessions

# Clear corrupted sessions
rawi history --cleanup

# Start fresh session
rawi ask --new-session "Starting fresh conversation"

Large input/output issues

Solutions:

# Limit input size
head -100 large-file.txt | rawi ask "Analyze this sample"

# Break large requests into chunks
split -l 50 large-file.txt chunk_
for chunk in chunk_*; do
    cat "$chunk" | rawi ask "Process this section"
done

Performance issues

Optimization tips:

1. Use appropriate models:

   # Fast for simple tasks
   rawi configure --model gpt-3.5-turbo
   
   # Powerful for complex tasks
   rawi configure --model gpt-4

2. Limit context size:

   # Use shorter, focused questions
   rawi ask "Quick summary of this error" < error.log

3. Local providers for speed:

   # Use Ollama for fast local responses
   rawi configure --provider ollama --model llama2

---

Advanced Usage

How do I create custom workflows?

Create shell scripts that combine Rawi with other tools:

development-helper.sh

#!/bin/bash
case "$1" in
    "review")
        git diff | rawi ask --act code-reviewer "Review these changes"
        ;;
    "commit")
        git diff --cached | rawi ask "Generate commit message"
        ;;
    "debug")
        cat "$2" | rawi ask --act debugging-expert "Help debug this code"
        ;;
esac

Can I integrate Rawi with my IDE?

Yes! Many ways to integrate:

VS Code: Create tasks or use terminal integration Vim/Neovim: Shell commands and custom functions Command palette: Add shell commands to your IDE

Example VS Code task:

{
  "label": "AI Code Review",
  "type": "shell",
  "command": "cat ${file} | rawi ask --act code-reviewer 'Review this code'"
}

How do I backup my configuration?

# Backup configuration directory
cp -r ~/.config/rawi/ ~/rawi-backup/

# Export specific profile
rawi configure --profile work --export > work-profile.json

# Export session history
rawi history --export --format json > history-backup.json

Can I use Rawi offline?

Partially! Use local providers:

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

# Pull a model
ollama pull llama2

# Configure Rawi
rawi configure --provider ollama --model llama2

# Now works offline
rawi ask "Help me with this code"

---

Best Practices

Security Best Practices

1. Protect API keys:

   # Use environment variables
   export OPENAI_API_KEY="sk-your-key"
   
   # Don't commit keys to git
   echo "*.env" >> .gitignore

2. Use local providers for sensitive data:

   # Ollama for private code
   rawi configure --profile private --provider ollama

3. Regular key rotation:

   # Update keys periodically
   rawi configure --provider openai --api-key sk-new-key

Cost Management

1. Use appropriate models:

   # Cheap for simple tasks
   rawi configure --profile budget --model gpt-3.5-turbo
   
   # Expensive for complex tasks
   rawi configure --profile premium --model gpt-4

2. Monitor usage:

   # Check API usage on provider websites
   # Set up billing alerts

3. Use local providers when possible:

   # Free with Ollama
   rawi configure --provider ollama --model llama2

Productivity Tips

1. Create aliases:

   alias rwask='rawi ask'
   alias rwreview='rawi ask --act code-reviewer'
   alias rwwrite='rawi ask --act technical-writer'

2. Use sessions effectively:

   # Topic-focused sessions
   rawi ask --new-session --session project-auth "Working on authentication"

3. Combine with other tools:

   # Git integration
   git diff | rawi ask --act code-reviewer "Review changes" | tee review.md

Getting Help

Where can I get more help?

• GitHub Repository: github.com/withrawi/rawi
• Documentation: This documentation site
• Issues: Report bugs on GitHub Issues
• Discussions: Community discussions on GitHub

How do I report bugs?

1. Check existing issues on GitHub
2. Provide reproduction steps
3. Include system information:

   rawi info
   node --version
   npm --version

4. Include error messages and logs

How do I request features?

1. Check GitHub Issues for existing requests
2. Create a new issue with:
   • Clear description of the feature
   • Use cases and benefits
   • Possible implementation approach

---

See Also

• Installation Guide — Detailed installation instructions
• Quick Start Guide — Get started quickly
• Troubleshooting — Detailed troubleshooting guide
• Configuration Guide — Complete configuration reference