# CLI Reference

Complete command-line interface reference for OpenQuery.

## 📋 Table of Contents

1. [Command Structure](#command-structure)
2. [Main Command: `openquery`](#main-command-openquery)
3. [Configure Command: `openquery configure`](#configure-command-openquery-configure)
4. [Exit Codes](#exit-codes)
5. [Examples by Use Case](#examples-by-use-case)
6. [Shell Integration](#shell-integration)

## Command Structure

OpenQuery uses [System.CommandLine](https://learn.microsoft.com/dotnet/standard/commandline/) for CLI parsing.

### Syntax
```bash
openquery [GLOBAL-OPTIONS] <COMMAND> [COMMAND-OPTIONS] [ARGUMENTS]
```

If no command specified, `openquery` (main command) is assumed.

### Help
```bash
openquery --help
openquery configure --help
```

Shows usage, options, examples.

### Version
```bash
openquery --version  # if implemented
```

---

## Main Command: `openquery`

Ask a question and get an AI-powered answer.

### Synopsis
```bash
openquery [OPTIONS] <question>
```

### Arguments

| Name | Arity | Type | Description |
|------|-------|------|-------------|
| `question` | ZeroOrMore | `string[]` | The question to ask (positional, concatenated with spaces) |

**Notes**:
- `ZeroOrMore` means you can omit the question (shows help)
- Multiple words are combined: `openquery what is quantum` → `"what is quantum"`
- Use quotes for questions with special characters: `openquery "what's the weather?"`

### Options

| Option | Aliases | Type | Default | Description |
|--------|---------|------|---------|-------------|
| `--chunks` | `-c` | `int` | `DefaultChunks` (config) | Number of top context chunks to pass to LLM |
| `--results` | `-r` | `int` | `DefaultResults` (config) | Number of search results per query |
| `--queries` | `-q` | `int` | `DefaultQueries` (config) | Number of search queries to generate |
| `--short` | `-s` | `bool` | `false` | Request a concise answer |
| `--long` | `-l` | `bool` | `false` | Request a detailed answer |
| `--verbose` | `-v` | `bool` | `false` | Show detailed progress information |

**Option Notes**:
- `--short` and `--long` are flags; if both specified, `--long` takes precedence
- Integer options validate as positive numbers (parsed by System.CommandLine)
- Defaults come from config file or hardcoded (3, 5, 3 respectively)

### Behavior

1. Loads API key (env `OPENROUTER_API_KEY` or config file)
2. Loads model (env `OPENROUTER_MODEL` or config)
3. Executes workflow:
   - Generate queries (if `--queries > 1`)
   - Run search pipeline
   - Stream final answer
4. Exits with code 0 on success, 1 on error

### Examples

```bash
# Basic
openquery "What is the capital of France?"

# With options
openquery -q 5 -r 10 -c 4 "Explain quantum computing"

# Short answer
openquery -s "Who won the 2024 election?"

# Verbose mode
openquery -v "How does photosynthesis work?"

# Combined
openquery -l -v -q 8 "History of the internet"
```

---

## Configure Command: `openquery configure`

Configure OpenQuery settings (API key, model, defaults).

### Synopsis
```bash
openquery configure [OPTIONS]
```

### Options

| Option | Type | Description |
|--------|------|-------------|
| `--interactive` / `-i` | `bool` | Launch interactive configuration wizard |
| `--key` | `string` | Set OpenRouter API key |
| `--model` | `string` | Set default LLM model |
| `--queries` | `int?` | Set default number of queries |
| `--chunks` | `int?` | Set default number of chunks |
| `--results` | `int?` | Set default number of results |

**Note**: Nullable options (`int?`) only update if provided.

### Behavior

- **Interactive mode** (`-i`): Prompts for each setting with current defaults shown in brackets
- **Non-interactive**: Only updates provided options, leaves others untouched
- Writes to `~/.config/openquery/config` (creates directory if missing)
- Overwrites entire file (not incremental)

### Interactive Mode Details

Models presented with numbered menu:

```
Available models:
1. qwen/qwen3.5-flash-02-23
2. qwen/qwen3.5-122b-a10b
3. minimax/minimax-m2.5
4. google/gemini-3-flash-preview
5. deepseek/deepseek-v3.2
6. moonshotai/kuki-k2.5
Model [qwen/qwen3.5-flash-02-23]:
```

- Enter number (1-6) to select preset
- Or enter custom model string (any OpenRouter model)

### Examples

```bash
# Interactive wizard
openquery configure -i

# Set just API key
openquery configure --key "sk-or-xxxxxxxxxxxx"

# Set multiple defaults
openquery configure --model "google/gemini-3-flash-preview" --queries 5 --chunks 4

# Update model only
openquery configure --model "deepseek/deepseek-v3.2"
```

---

## Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success - answer generated and streamed |
| `1` | Error - API key missing, network failure, or exception |

**Usage in scripts**:
```bash
openquery "question"
if [ $? -eq 0 ]; then
    echo "Success"
else
    echo "Failed" >&2
fi
```

---

## Examples by Use Case

### Quick Facts
```bash
openquery -s "capital of France"
```
Fast, concise, minimal tokens.

### Research Paper
```bash
openquery -l -q 5 -r 10 -c 4 "quantum entanglement experiments"
```
Multiple angles, deep sources, detailed synthesis.

### News & Current Events
```bash
openquery -v "latest news about OpenAI"
```
See everything: queries, results, which sources fetched.

### Troubleshooting
```bash
# Reduce scope if errors
openquery -q 1 -r 2 "test question"
```

### Save Answer to File
```bash
openquery "question" 2>/dev/null | sed 's/.\x08//g' > answer.md
```

(Removes spinner characters)

### Batch Processing
```bash
for q in $(cat questions.txt); do
    echo "## $q" >> all-answers.md
    openquery -s "$q" 2>/dev/null | sed 's/.\x08//g' >> all-answers.md
    echo "" >> all-answers.md
done
```

---

## Shell Integration

### Aliases (add to ~/.bashrc or ~/.zshrc)

```bash
# Short alias
alias oq='openquery'

# Presets
alias oqs='openquery -s'              # short
alias oql='openquery -l'              # long
alias oqv='openquery -v'              # verbose
alias oqr='openquery -q 5 -r 10 -c 4' # research mode

# Config shortcuts
alias oqcfg='openquery configure -i'
```

### Functions

```bash
# Save answer cleanly (removes spinner chars)
oqsave() {
    local query="$*"
    local filename="answer-$(date +%Y%m%d-%H%M%S).md"
    openquery "$query" 2>/dev/null | sed 's/.\x08//g' > "$filename"
    echo "Saved to $filename"
}

# Search and grep results
oqgrep() {
    openquery "$1" 2>/dev/null | sed 's/.\x08//g' | grep -i "$2"
}
```

### Environment Setup Script

```bash
# ~/.local/bin/openquery-env.sh
export OPENROUTER_API_KEY="sk-or-..."
export OPENROUTER_MODEL="qwen/qwen3.5-flash-02-23"
export SEARXNG_URL="http://localhost:8002"
```

Source it: `source ~/.local/bin/openquery-env.sh`

---

## Next Steps

- **[Configuration](configuration.md)** - Set up your environment
- **[Usage](usage.md)** - Learn usage patterns and tips
- **[Troubleshooting](troubleshooting.md)** - Fix common problems

---

**Quick Reference Card**

```
# Ask
openquery "question"
openquery -s "quick fact"
openquery -l -q 5 "deep research"

# Configure
openquery configure -i
openquery configure --key "..."
openquery configure --model "..."

# Debug
openquery -v "question"

# Help
openquery --help
```