234 lines
5 KiB
Markdown
234 lines
5 KiB
Markdown
# 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.
|