OpenQuery/docs/api/cli.md

CLI Reference

Complete command-line interface reference for OpenQuery.

📋 Table of Contents

1. Command Structure
2. Main Command: openquery
3. Configure Command: openquery configure
4. Exit Codes
5. Examples by Use Case
6. Shell Integration

Command Structure

OpenQuery uses System.CommandLine for CLI parsing.

Syntax

openquery [GLOBAL-OPTIONS] <COMMAND> [COMMAND-OPTIONS] [ARGUMENTS]

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

Help

openquery --help
openquery configure --help

Shows usage, options, examples.

Version

openquery --version  # if implemented

---

Main Command: openquery

Ask a question and get an AI-powered answer.

Synopsis

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

# 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

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

# 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:

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

---

Examples by Use Case

Quick Facts

openquery -s "capital of France"

Fast, concise, minimal tokens.

Research Paper

openquery -l -q 5 -r 10 -c 4 "quantum entanglement experiments"

Multiple angles, deep sources, detailed synthesis.

News & Current Events

openquery -v "latest news about OpenAI"

See everything: queries, results, which sources fetched.

Troubleshooting

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

Save Answer to File

openquery "question" 2>/dev/null | sed 's/.\x08//g' > answer.md

(Removes spinner characters)

Batch Processing

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)

# 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

# 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

# ~/.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 - Set up your environment
• Usage - Learn usage patterns and tips
• Troubleshooting - 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