docs: add comprehensive documentation with README and detailed guides
- Add user-friendly README.md with quick start guide - Create docs/ folder with structured technical documentation: - installation.md: Build and setup instructions - configuration.md: Complete config reference - usage.md: CLI usage guide with examples - architecture.md: System design and patterns - components/: Deep dive into each component (OpenQueryApp, SearchTool, Services, Models) - api/: CLI reference, environment variables, programmatic API - troubleshooting.md: Common issues and solutions - performance.md: Latency, throughput, and optimization - All documentation fully cross-referenced with internal links - Covers project overview, architecture, components, APIs, and support See individual files for complete documentation.
This commit is contained in:
OpenQuery Documentation
309
docs/api/cli.md
Normal file
309
docs/api/cli.md
Normal file
@@ -0,0 +1,309 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user