web-search

# Web Search

Free web search using DuckDuckGo's Instant Answer API. No API key required.

## Quick Start

```bash
# Basic search
cd /home/hxx/clawd/tools && ./web-search.sh "your query"

# Examples
./web-search.sh "what is artificial intelligence"
./web-search.sh "python programming"
./web-search.sh "define recursion"
./web-search.sh "2+2"
```

## Command-Line Options

### Core Options
- `-h, --help` - Display help message with usage examples
- `--format <format>` - Output format: `text`, `markdown`, `plain` (default: `text`)
  - `text`: Colored terminal output (default)
  - `markdown`: Clean markdown format (no ANSI colors)
  - `plain`: Plain text without colors
- `--no-color` - Disable colored output (same as `--format plain`)
- `--max-related <N>` - Control number of related topics to show (default: 5)
- `--quiet` - Minimal output mode (just results, no headers/footer)

### Output to File
Use shell redirection to save results to file:

```bash
# Save to file
./web-search.sh "query" > output.txt

# With markdown format
./web-search.sh --format markdown "query" > results.md

# With no colors for logs
./web-search.sh --no-color "query" > search.log
```

## What It Returns

The tool provides several result types:

- **Answers** - Direct answers for calculations, conversions, weather, etc.
- **Abstracts** - Wikipedia-style summaries with source and URL
- **Definitions** - Word/term definitions
- **Related Topics** - Additional relevant results (configurable, 5 default)

## Best Practices

1. **Be specific** - More specific queries get better instant answers
2. **Try variations** - If no results, rephrase your query
3. **Use for facts** - Definitions, calculations, quick lookups work best
4. **Check URL** - Always provides DuckDuckGo link for full search
5. **Use appropriate format**:
   - Terminal output: `--format text` (colored, default)
   - Documentation: `--format markdown` > file.md`
   - Logs/piping: `--format plain` or `--no-color`

## Limitations

- No full web search results (only instant answers)
- Some queries return limited results depending on DuckDuckGo's data
- Character encoding issues in some abstracts (known limitation)
- Requires internet access to query DuckDuckGo API
- Not all query types return instant answers (e.g., complex math like `sqrt(144)`)
- Definitions may not always be available for all terms
- Recent news may not appear (DuckDuckGo focuses on evergreen content)

## Usage Examples

### Basic Search
```bash
# Simple query
./web-search.sh "open source AI models"

# Wikipedia-style query
./web-search.sh "what is recursion"
```

### Markdown Format
```bash
# Clean markdown output
./web-search.sh --format markdown "python programming"

# Save to markdown file
./web-search.sh --format markdown "AI research" > research.md
```

### Plain/No Color
```bash
# For logs or piping
./web-search.sh --format plain "search query"

# Disable colors explicitly
./web-search.sh --no-color "search query"
```

### Control Related Topics
```bash
# Show fewer related topics
./web-search.sh --max-related 3 "machine learning"

# Show more related topics
./web-search.sh --max-related 10 "open source"
```

### Quiet Mode
```bash
# Minimal output (just results)
./web-search.sh --quiet "what is 42 + 7"
```

### Combined Options
```bash
# Markdown, no color, saved to file
./web-search.sh --format markdown --no-color "topic" > results.md

# Quiet with custom related count
./web-search.sh --quiet --max-related 2 "definition"
```

## Tested Scenarios

Tested and verified to work:
- ✅ Calculations: `2+2`, `10% of 500`
- ✅ Conversions: `100 miles to km`
- ✅ Wikipedia queries: `what is artificial intelligence`
- ✅ Programming: `what is python`, `how to install docker`
- ✅ People: `who is Elon Musk`
- ✅ Scientific facts: `speed of light`
- ✅ Weather: `weather in Tokyo`
- ✅ Edge cases: empty queries, special characters, no results
- ✅ Output formats: text, markdown, plain
- ✅ Flags: --help, --format, --no-color, --max-related, --quiet

See [test-outputs.md](test-outputs.md) for detailed test results.

## Troubleshooting

### "No direct results found"
Try rephasing your query or using the provided DuckDuckGo URL for full search.

### Network errors
Check internet connection. Tool requires network access.

### Character encoding issues
Some abstracts display garbled characters. This is a known issue with basic parsing (install `jq` for better results).

### "jq not found" warning
The tool works without `jq` using basic text extraction, but installing `jq` improves JSON parsing:
```bash
# Ubuntu/Debian
sudo apt-get install jq

# macOS
brew install jq

# Via package managers
npm install -g jq
```

## Output Format

### Text Format (default)
- **Blue** - Headers and search info
- **Green** - Result markers and content
- **Yellow** - Sources, URLs, and warnings
- **Red** - Errors

Use `--format plain` or `--no-color` to disable colors.

### Markdown Format
Clean markdown with:
- `##` headers for sections
- `**bold**` for emphasis
- `-` bullet lists
- `*italics*` for metadata
- `[links]()` for URLs

### Plain Format
No ANSI codes or markdown formatting - suitable for logs and piping.

## Requirements

- `curl` or `wget` (for HTTP requests)
- Optional: `jq` (for better JSON parsing)