65ca2401ae
- 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.
310 lines
7.0 KiB
Markdown
310 lines
7.0 KiB
Markdown
# 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
|
|
```
|