OpenQuery/docs/usage.md

Usage Guide

Complete reference for using the OpenQuery command-line interface.

📋 Table of Contents

1. Basic Usage
2. Command Reference
3. Examples
4. Output Format
5. Tips and Tricks

Basic Usage

Simplest Form

openquery "your question here"

That's it! OpenQuery will:

1. Generate search queries
2. Search the web
3. Extract relevant content
4. Stream an answer with sources

Common Pattern

openquery [OPTIONS] "your question"

Quotes around the question are recommended to preserve spaces.

Command Reference

Main Command

openquery [options] <question>

Ask a question and get an AI-powered answer with citations.

Arguments:

• question (positional, one or more words) - The question to ask

Options:

Option	Aliases	Type	Default	Description
--chunks	-c	int	3 (from config)	Number of top relevant content chunks to include in context
--results	-r	int	5 (from config)	Number of search results to fetch per generated query
--queries	-q	int	3 (from config)	Number of search queries to generate from your question
--short	-s	bool	false	Request a concise, to-the-point answer
--long	-l	bool	false	Request a detailed, comprehensive answer
--verbose	-v	bool	false	Show detailed progress information and debug output

Behavior:

• Short and long are mutually exclusive but can both be omitted (balanced answer)
• If both --short and --long are specified, --long takes precedence
• Options override configuration file defaults

openquery configure [options]

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

Options:

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

Examples:

# Interactive wizard
openquery configure -i

# Set just the API key
openquery configure --key "sk-or-..."

# Set multiple defaults non-interactively
openquery configure --model "deepseek/deepseek-v3.2" --queries 5 --chunks 4

Note: Options with ? are nullable; only provided values are updated.

Examples

Everyday Queries

Simple factual question:

openquery "What is the speed of light?"

Multi-word question:

openquery "How do solar panels work?"

Question with special characters:

openquery "What's the weather in New York?"

Customizing Output

Get a quick answer:

openquery -s "Who is the CEO of Tesla?"

Output: "Elon Musk is the CEO of Tesla." (minimal explanation)

Get detailed analysis:

openquery -l "Explain how nuclear fusion works"

Output: Multi-paragraph detailed explanation with scientific details

See everything:

openquery -v "What is machine learning?"

Output: Shows all progress messages alongside the answer

Adjusting Search Depth

Minimal search (fast, cheap):

openquery -q 1 -r 2 -c 1 "What time is it in London?"

• 1 generated query
• 2 results per query
• 1 context chunk

Thorough research (slow, comprehensive):

openquery -q 8 -r 15 -c 5 "History and applications of cryptography"

• 8 diverse queries
• 15 results each
• 5 top chunks

Balanced (recommended defaults):

openquery "Latest advancements in CRISPR technology"

• 3 queries
• 5 results each
• 3 top chunks

Combining Options

Verbose custom search:

openquery -v -q 5 -r 10 -c 4 "What are the ethical implications of AI?"

Short answer with more context:

openquery -s -c 5 "Python vs JavaScript for web development"

Long answer, lots of research:

openquery -l -q 10 -r 20 -c 6 "Complete guide to quantum computing"

Practical Use Cases

News and Current Events:

openquery "Latest developments in the Ukraine conflict"

Technical Questions:

openquery "How to set up a PostgreSQL replication cluster"

Health Information (verify with doctor!):

openquery "What are the symptoms of vitamin D deficiency?"

Cooking:

openquery "How to make authentic Italian pizza dough"

Travel:

openquery "Best things to do in Tokyo in spring"

Programming:

openquery "Rust vs Go for backend development in 2025"

Configuration Examples

Set up for the first time:

openquery configure -i
# Follow prompts to enter API key, choose model, set defaults

Switch to a different model:

openquery configure --model "google/gemini-3-flash-preview"

Update default number of queries:

openquery configure --queries 5

Set cost-effective defaults:

openquery configure --model "qwen/qwen3.5-flash-02-23" --queries 2 --chunks 2 --results 3

Check your configuration:

cat ~/.config/openquery/config

Output Format

Standard Output (Streaming)

The answer streams in real-time, character by character, like this:

⠋ Generating search queries...  (spinner with status)
⠹ Searching web...
⠸ Fetching articles...
⠼ Processing embeddings...
⠴ Generating answer...
Assistant: Quantum entanglement is a phenomenon where pairs or groups of
particles interact in ways such that the quantum state of each particle
cannot be described independently of the others, even when separated by
large distances.

[Source 1: Understanding Quantum Mechanics](https://example.com/quantum)
[Source 2: Quantum Physics Overview](https://example.com/physics)

Verbose Mode Output (-v)

When --verbose is enabled, you see detailed progress:

[Generating 3 search queries based on your question...]
[Generated queries: 
  1. quantum entanglement definition
  2. how quantum entanglement works
  3. quantum entanglement Bell's theorem
]
[Searching web for 'quantum entanglement definition'...]
[Searching web for 'how quantum entanglement works'...]
[Searching web for 'quantum entanglement Bell's theorem'...]
[Fetched 15 search results total]
[Fetching article 1/12: physicsworld.com]
[Fetching article 2/12: nature.com]
...
[Fetching article 12/12: scientificamerican.com]
[Extracted 48 content chunks]
[Generating embeddings: batch 1/4]
[Generating embeddings: batch 2/4]
[Generating embeddings: batch 3/4]
[Generating embeddings: batch 4/4]
[Ranked chunks by relevance]
[Found top 3 most relevant chunks overall. Generating answer...]

Assistant: Quantum entanglement is a fundamental phenomenon in quantum
mechanics where...

Source Citations

Sources are formatted as markdown links in the answer:

[Source 1: Article Title](https://example.com/article)

These appear inline where the AI references that source. Multiple sources can be cited in a single paragraph.

Error Output

Errors are written to stderr and exit with non-zero status:

[Error] API Key is missing. Set OPENROUTER_API_KEY environment variable or run 'configure -i'.

Tips and Tricks

Speed Tips

1. Reduce concurrency limits (edit SearchTool.cs if constantly rate-limited)
2. Reduce --results - fewer articles to fetch and process
3. Reduce --queries - fewer parallel searches
4. Use local SearxNG - minimize network latency to search backend
5. Cache results - future enhancement could add caching

Quality Tips

1. Increase --chunks to 4-5 for complex topics
2. Increase --queries to 5-8 for broad exploration
3. Use --long for deep topics that need elaboration
4. Check -v output to see which sources were selected
5. Try different models - some are better at synthesis, others at facts

Cost Tips

1. Use qwen/qwen3.5-flash-02-23 - cheapest good model
2. Reduce --chunks and --results** - fewer tokens in context
3. Use --short - shorter answers use fewer completion tokens
4. Monitor usage at openrouter.ai dashboard

Workflow Tips

Iterative deepening:

# Start broad
openquery -v "machine learning"

# Identify subtopics from answer, then dive deeper
openquery "What is transformer architecture in LLMs?"

Compare answers:

# Same question with different models
OPENROUTER_MODEL="qwen/qwen3.5-flash-02-23" openquery "question"
OPENROUTER_MODEL="google/gemini-3-flash-preview" openquery "question"

Save answers:

openquery "What is Docker?" > answer.md
# answer.md will contain the streamed output (including spinner chars, so filter):
openquery "What is Docker?" 2>/dev/null | sed 's/.\x08//g' > clean-answer.md

Shell Aliases and Functions

Add to ~/.bashrc or ~/.zshrc:

# Short alias
alias oq='openquery'

# With common options
alias oql='openquery -l -q 5 -r 10'  # long, thorough
alias oqs='openquery -s'              # short
alias oqv='openquery -v'              # verbose

# Function to save output cleanly
oqsave() {
    openquery "$@" 2>/dev/null | sed 's/.\x08//g' > "answer-$(date +%Y%m%d-%H%M%S).md"
}

Scripting

#!/bin/bash
# batch-questions.sh

while IFS= read -r question; do
    echo "## $question" >> research.md
    echo "" >> research.md
    openquery -l "$question" 2>/dev/null | sed 's/.\x08//g' >> research.md
    echo "" >> research.md
done < questions.txt

Chaining with Other Tools

Pipe to jq (if you modify to output JSON):

# Future: openquery --json "question" | jq '.answer'

Pipe to pbcopy (macOS) or xclip (Linux):

openquery "quick fact" 2>/dev/null | sed 's/.\x08//g' | pbcopy

Filter sources:

openquery "topic" 2>/dev/null | sed 's/.\x08//g' | grep -E '^\[Source'

Keyboard Interrupts

• Ctrl+C during processing: Cancels current operation, exits gracefully
• Ctrl+C during streaming answer: Stops streaming, shows partial answer
• Ctrl+Z (suspend): Not recommended; may leave background tasks running

OpenQuery uses proper cancellation tokens to clean up resources on interrupt.

Exit Codes

Code	Meaning
0	Success - answer was generated
1	Error - see stderr message
2	Configuration error (missing API key)

You can check the exit code in shell scripts:

openquery "question"
if [ $? -eq 0 ]; then
    echo "Success!"
else
    echo "Failed"
fi

Limitation and Workarounds

Question Length

Very long questions (>2000 chars) may be truncated by the LLM's context window or cause token limits.

Workaround: Keep questions concise; discuss complex multi-part questions separately.

Answer Length Limits

The LLM may hit max_tokens limits for very complex questions.

Workaround: Use --long flag (already maximizes allowed tokens) or break into sub-questions.

Rate Limiting

OpenRouter may rate limit if you send too many requests too quickly.

Symptoms: 429 errors, occasional timeouts.

Workaround: The built-in retry (Polly) handles this automatically. For persistent issues:

• Reduce concurrency (edit code)
• Add delays between queries
• Upgrade OpenRouter plan

SearxNG Timeouts

Large SearxNG responses or slow targets may timeout.

Workaround: Reduce --results or check SearxNG logs. Nothing to do on OpenQuery side (HTTP client timeout is ~30s default).

---

Next Steps

• Architecture - Understand how OpenQuery works under the hood
• Configuration - Fine-tune your setup
• Troubleshooting - Solve common problems

---

Quick Reference Card

# Basic
openquery "question"

# Quick fact
openquery -s "question"

# Deep research
openquery -l -q 5 -r 10 -c 4 "question"

# See progress
openquery -v "question"

# Configure
openquery configure -i

# Check config
cat ~/.config/openquery/config