# Quick Start: Using the Dart CLI REPL

## Setup

### 1. Install dependencies (for Flutter app parts)
```bash
flutter pub get
```

### 2. Set up API key
Choose one:

**Option A: OpenRouter (vendor-neutral, recommended)**
```bash
export OPENROUTER_API_KEY="sk-or-..."
```

**Option B: Anthropic**
```bash
export ANTHROPIC_API_KEY="sk-ant-..."
```

### 3. Start the REPL
```bash
dart lib/clawd_code.dart
# OR (if you have it installed as a CLI tool)
clawd_code
```

You'll see:
```
clawd_code 0.1.0
Dart CLI migration shell. Type /help for commands.
clawd>
```

---

## Using the REPL

### Free-form prompts (new functionality!)
Just type any question:

```
clawd> How do I create a web server in Go?
```

The model will respond and may use tools:
```
→ Calling Bash
← Bash returned: Created main.go with basic HTTP server...

To create a simple web server in Go, I've created a main.go file
with an HTTP server that listens on port 8080...
```

### Commands (slash-prefixed)
```
clawd> /help                    # See all commands
clawd> /model                   # View/change model
clawd> /status                  # Show session status
clawd> /effort high             # Set effort level
clawd> /clear                   # Clear screen
```

### Tool invocations (syntax: `toolname: args`)
```
clawd> bash: ls -la
clawd> read: /path/to/file
clawd> grep: pattern lib/src
clawd> glob: **/*.dart
```

### Conversation history
Your conversation is maintained in memory during the session:
```
clawd> Write a function to reverse a string
<model responds with code>

clawd> Can you add error handling?
<model recalls previous code and improves it>
```

---

## What Works

✅ **Free-form prompts** → Model processes them  
✅ **Model tool calls** → Bash, file ops, search, etc. execute  
✅ **Streaming** → See responses as they're generated  
✅ **Conversation history** → Model remembers context  
✅ **Cost tracking** → See how much you've spent  
✅ **Multiple vendors** → Works with OpenRouter or Anthropic  

---

## What Doesn't Work Yet

❌ **Real background tasks** → `/tasks` stores metadata only, no execution  
❌ **Real MCP servers** → `/mcp` is simulated  
❌ **Real agents** → `/agents` is simulated  
❌ **Some commands** → 25+ commands not yet ported  

---

## Environment Variables

Control behavior with these variables:

```bash
# API selection
export USE_OPENROUTER=true          # Prefer OpenRouter
export USE_ANTHROPIC=true          # Prefer Anthropic

# API keys
export OPENROUTER_API_KEY="..."
export ANTHROPIC_API_KEY="..."

# Model override (if not using /model command)
export CLAUDE_CODE_MODEL="gpt-4"    # OpenRouter model

# Debug
export CLAWD_DEBUG=true             # More verbose output
```

---

## Troubleshooting

### "No API key configured"
```bash
export OPENROUTER_API_KEY="your-key-here"
# OR
export ANTHROPIC_API_KEY="your-key-here"
```

### "Base URL not configured"
This is the new vendor-neutral requirement. Set one of:
```bash
export OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"
export ANTHROPIC_BASE_URL="https://api.anthropic.com/v1"
export CLAUDE_CODE_BASE_URL="https://your-backend.com/api/v1"
```

### "Unknown model"
Set a valid model name:
```bash
/model claude-opus-4
# OR
/model openrouter/auto
```

### Model is slow
Check your API key is valid and you have quota available.

### Task not persisting
Tasks are saved to `~/.clawd_code/tasks/` as JSON files. Check that directory exists and is writable.

---

## Examples

### Example 1: Code generation
```
clawd> Write a Dart async function that fetches data from an API

<model responds with code, may call Bash to create a file>
```

### Example 2: File editing
```
clawd> Read lib/src/app.dart and explain the main entry point

<model calls Read tool, then explains>
```

### Example 3: Debugging
```
clawd> Search lib/ for all uses of BashTool

<model calls Grep, finds all references>
```

### Example 4: Web research
```
clawd> Search for best practices for Dart CLI development

<model calls WebSearch tool if available, returns current info>
```

---

## Cost Tracking

After each model call, you'll see:
```
$0.05 for this prompt (1,234 input + 456 output tokens)
Session total: $0.32
```

Costs saved to `~/.claude/last_session_cost.json` on exit.

---

## Next Steps

- [ ] Try `/help` to see all commands
- [ ] Try a free-form prompt about your codebase
- [ ] Use `/tasks create` to track work
- [ ] Use `/config` to see and change settings
- [ ] Use `/theme` to change appearance

---

## Architecture Note

This REPL implementation:
- ✅ Is vendor-neutral (works with OpenRouter, Anthropic, or custom backend)
- ✅ Works without any backend (model API is external, not local)
- ✅ Maintains conversation history in memory
- ✅ Integrates with full tool system (permissions, telemetry, etc.)
- ❌ Does not require Flutter (pure Dart CLI)

For the full Dart CLI experience without Flutter deps, run:
```bash
dart lib/clawd_code.dart
```

For the Flutter app with UI, run:
```bash
flutter run
```

Both use the same underlying model integration.