# GNO Usage Examples Real-world examples for common tasks. ## Getting Started ### Index a folder of docs ```bash # Initialize gno init # Add your docs folder gno collection add ~/Documents/work --name work # Build index gno index ``` ### Index multiple folders ```bash gno init gno collection add ~/notes --name notes --pattern "**/*.md" gno collection add ~/work/contracts --name contracts --pattern "**/*.{pdf,docx}" gno index ``` ## Searching ### Find by keywords ```bash # Simple search gno search "quarterly report" # More results gno search "budget" -n 20 # Filter to collection gno search "NDA" -c contracts ``` ### Find by meaning (semantic) ```bash # Semantic search finds related concepts gno vsearch "how to cancel subscription" # Even if docs say "terminate agreement" gno vsearch "end contract early" ``` ### Best quality search ```bash # Hybrid combines keywords + semantics + reranking gno query "deployment process" # See how results were found gno query "deployment" --explain ``` ## Getting Answers ### Q&A with citations ```bash # Just retrieve relevant chunks gno ask "what are the payment terms" # Get an AI-generated answer gno ask "what are the payment terms" --answer ``` ### Scoped answers ```bash # Search only contracts gno ask "termination clause" -c contracts --answer # Limit answer length gno ask "summarize project goals" --answer --max-answer-tokens 200 ``` ## Reading Documents ### Get full document ```bash # By URI gno get gno://work/readme.md # By document ID gno get "#a1b2c3d4" # With line numbers gno get gno://notes/meeting.md --line-numbers ``` ### Get specific lines ```bash # Start at line 50 gno get gno://work/report.md --from 50 # Get 20 lines starting at 100 gno get gno://work/report.md --from 100 -l 20 ``` ### List documents ```bash # All documents gno ls # In a collection gno ls work # As JSON gno ls --json ``` ## Search & Retrieve Full Content ### Pipeline: Search then get ```bash # Find documents, get full content of top result gno search "api design" --files | head -1 | cut -d, -f3 | xargs gno get # JSON pipeline - get first result's full content gno query "auth" --json | jq -r '.results[0].uri' | xargs gno get # Get multiple results gno search "error handling" --json | jq -r '.results[].uri' | xargs gno multi-get ``` ## JSON Output (Scripting) ### Search results to JSON ```bash # Get URIs of matches gno search "api endpoint" --json | jq '.[] | .uri' # Get snippets gno search "config" --json | jq '.[] | {uri, snippet}' ``` ### Check index health ```bash # Get stats gno status --json | jq '{docs: .totalDocuments, chunks: .totalChunks}' # Run diagnostics gno doctor --json ``` ### Batch processing ```bash # Export all document IDs gno ls --json | jq -r '.[].docid' > doc-ids.txt # Search and process results gno search "error" --json | jq -r '.[] | .uri' | while read uri; do echo "Processing: $uri" gno get "$uri" > "output/$(basename $uri)" done ``` ## Maintenance ### Update index after changes ```bash # Sync files from disk gno update # Full re-index gno index ``` ### Git integration ```bash # Pull and re-index gno index --git-pull # Useful for docs repos gno update --git-pull ``` ### Model management ```bash # List models and status gno models list # Switch to quality preset gno models use quality # Download models gno models pull ``` ## Note Linking ### View outgoing links ```bash # List all links from a document gno links gno://notes/readme.md # Filter by type gno links gno://notes/readme.md --type wiki gno links gno://notes/readme.md --type markdown # Show only broken links gno links gno://notes/readme.md --broken ``` ### Find backlinks ```bash # Find all documents linking TO this one gno backlinks gno://notes/api-design.md # More results gno backlinks gno://notes/api-design.md -n 50 ``` ### Find related notes ```bash # Find semantically similar documents gno similar gno://notes/auth.md # Stricter threshold (default: 0.7) gno similar gno://notes/auth.md --threshold 0.85 # Search across all collections gno similar gno://notes/auth.md --cross-collection ``` ### Wiki link syntax ```markdown # In your documents: See [[API Design]] for details. Check [[work:Project Plan]] for cross-collection link. Read [[Security#OAuth]] for specific section. ``` ## Tagging ### List and manage tags ```bash # List all tags with counts gno tags # Filter by collection gno tags -c work # Filter by prefix (hierarchical) gno tags --prefix project/ ``` ### Add/remove tags ```bash # Add tag to document gno tags add gno://work/readme.md project/api # Remove tag gno tags rm gno://work/readme.md draft # Tags in frontmatter are extracted automatically cat myfile.md # --- # tags: [project/web, status/review] # --- ``` ### Filter search by tags ```bash # Find docs with ANY of these tags (OR) gno search "api" --tags-any project,work # Find docs with ALL of these tags (AND) gno query "auth" --tags-all security,reviewed # Combine with other filters gno ask "deployment steps" -c work --tags-any devops --answer ``` ## Tips ### Search Modes | Command | Time | Use When | | ---------------------- | ------- | ---------------------------- | | `gno search` | instant | Exact keyword matching | | `gno vsearch` | ~0.5s | Finding similar concepts | | `gno query --fast` | ~0.7s | Quick lookups | | `gno query` | ~2-3s | Default, balanced | | `gno query --thorough` | ~5-8s | Best recall, complex queries | **Agent retry strategy**: Use default mode first. If no results: 1. Rephrase the query (free, often helps) 2. Try `--thorough` for better recall ### Output formats ```bash # Human readable (default) gno search "query" # JSON (scripting) gno search "query" --json # File list (for piping) gno search "query" --files # CSV (spreadsheets) gno search "query" --csv # Markdown (docs) gno search "query" --md ``` ### Large result sets ```bash # Increase limit gno search "common term" -n 50 # Filter by score gno search "common term" --min-score 0.7 # Get full content gno search "term" --full ```