CLI Reference

GNO command-line interface guide.

Full specification: See spec/cli.md for exhaustive command documentation.

Quick Reference

Global Flags

All commands accept:

--index <name>    Use alternate index (default: "default")
--config <path>   Override config file path
--no-color        Disable colored output
--no-pager        Disable automatic paging of long output
--verbose         Enable verbose logging
--yes             Non-interactive mode
--offline         Use cached models only (no auto-download)
--skill           Output SKILL.md for agent discovery and exit

Pager: Long output is automatically piped through a pager when in terminal mode. Uses $PAGER if set, otherwise less -R (Unix) or more (Windows). Disable with --no-pager.

Offline mode: Use --offline or set HF_HUB_OFFLINE=1 to prevent auto-downloading models. Set GNO_NO_AUTO_DOWNLOAD=1 to disable auto-download while still allowing explicit gno models pull.

Output format flags (--json, --files, --csv, --md, --xml) are per-command. See spec/cli.md for which commands support which formats.

Search Commands

gno search

Full-text search using document-level BM25 with Snowball stemmer.

gno search "project deadlines"
gno search "error handling" -n 5
gno search "auth" --json
gno search "meeting" --files

Document-level indexing: Finds documents where terms appear anywhere, even across sections. “authentication JWT” matches docs with those terms in different parts.

Snowball stemming: “running” matches “run”, “scored” matches “score”, plurals match singulars.

Options:

• -n, --limit <n> - Limit results (default: 5; 20 with –json/–files)
• --min-score <n> - Minimum score threshold (0-1)
• --full - Show full document content (not just snippet)
• --line-numbers - Show line numbers in snippets
• --lang <code> - Filter by detected language in code blocks
• --tags-all <tags> - Filter: docs must have ALL tags (comma-separated)
• --tags-any <tags> - Filter: docs must have ANY tag (comma-separated)

gno vsearch

Semantic similarity search using vector embeddings with contextual chunking.

gno vsearch "how to handle errors gracefully"
gno vsearch "authentication best practices" --json

Contextual embeddings: Each chunk is embedded with its document title prepended, helping the model distinguish context (e.g., “configuration” in React vs database docs).

Same options as gno search, including --tags-all and --tags-any filters. Requires embed model.

gno query

Hybrid search combining BM25 and vector results. This is the recommended search command for most use cases.

gno query "database optimization"
gno query "API design patterns" --explain
gno query "auth" --fast              # Fastest: ~0.7s
gno query "auth" --thorough          # Full pipeline: ~5-8s
gno query "auth" --tags-all work,backend   # Filter by tags

Search modes:

• Default (~2-3s): Skip expansion, with reranking. Best balance of speed and quality.
• --fast (~0.7s): Skip both expansion and reranking. Use for quick lookups.
• --thorough (~5-8s): Full pipeline with LLM expansion and reranking. Best recall.

Pipeline features:

• Strong signal detection: Skips expensive LLM expansion when BM25 has confident match
• 2× weight for original query: Prevents dilution by LLM-generated variants
• Tiered top-rank bonus: +0.05 for #1, +0.02 for #2-3
• Chunk-level reranking: Best chunk per doc (4K max) for 25× faster reranking

Additional options:

• --fast - Skip expansion and reranking (fastest, ~0.7s)
• --thorough - Enable query expansion (slower, ~5-8s)
• --no-expand - Disable query expansion
• --no-rerank - Disable cross-encoder reranking
• --explain - Show detailed scoring breakdown (to stderr)
• --tags-all <tags> - Filter: docs must have ALL tags
• --tags-any <tags> - Filter: docs must have ANY tag

The --explain flag outputs:

• BM25 scores per result
• Vector similarity scores
• RRF fusion scores (with variant weights)
• skipped_strong indicator if expansion was skipped
• Rerank scores (if enabled)
• Final blended scores

See How Search Works for details on the scoring pipeline.

gno ask

Search and optionally generate an AI answer. Combines retrieval with optional LLM-generated response.

gno ask "what is the project goal"
gno ask "summarize the auth discussion" --answer
gno ask "explain the auth flow" --answer --show-sources
gno ask "quick lookup" --fast            # Fastest retrieval
gno ask "complex topic" --thorough       # Best recall

Full-document context: When --answer is used, GNO passes complete document content to the generation model, not truncated snippets. This ensures the LLM sees tables, code examples, and full context needed for accurate answers.

Preset requirement: For documents with markdown tables or structured data, use the quality preset (gno models use quality). Smaller models cannot reliably parse tabular content. This only applies to standalone --answer usage. When AI agents (Claude Code, Codex) call GNO via MCP/skill/CLI, they handle answer generation.

Options:

• --fast - Skip expansion and reranking (fastest)
• --thorough - Enable query expansion (slower, better recall)
• --answer - Generate grounded AI answer (requires gen model)
• --no-answer - Force retrieval-only output
• --max-answer-tokens <n> - Limit answer length
• --show-sources - Show all retrieved sources, not just cited ones
• -n, --limit <n> - Max source results
• -c, --collection <name> - Filter by collection
• --lang <code> - Language hint (BCP-47)
• --tags-all <tags> - Filter: docs must have ALL tags
• --tags-any <tags> - Filter: docs must have ANY tag

Document Commands

gno get

Retrieve document content by reference. Supports multiple reference formats:

• #abc123 - Document ID (hash prefix)
• gno://collection/path/to/file - Virtual URI
• collection/path - Collection + relative path

gno get abc123def456
gno get "gno://notes/projects/readme.md"
gno get notes/projects/readme.md --json
gno get abc123 --from 50 -l 100  # Lines 50-150

Options:

• --from <line> - Start output at line number (1-indexed)
• -l, --limit <lines> - Limit to N lines
• --line-numbers - Prefix lines with numbers
• --source - Include source metadata

gno multi-get

Retrieve multiple documents at once.

gno multi-get abc123 def456 ghi789
gno multi-get abc123 def456 --max-bytes 10000

Options:

• --max-bytes <n> - Limit bytes per document (truncates long docs)

gno ls

List indexed documents. Optional scope argument filters results.

gno ls                    # All documents
gno ls notes              # Documents in 'notes' collection
gno ls gno://notes/proj   # Documents under path prefix
gno ls --json
gno ls --files

Options:

• [scope] - Filter by collection name or URI prefix

Collection Commands

gno collection add

Add a collection to index.

gno collection add ~/notes --name notes
gno collection add ~/code --name code --pattern "**/*.ts" --exclude node_modules

Options:

• -n, --name <name> - Collection identifier (required)
• --pattern <glob> - File matching pattern
• --include <exts> - Extension allowlist (CSV)
• --exclude <patterns> - Exclude patterns (CSV)
• --update <cmd> - Shell command to run before indexing

gno collection list

List configured collections.

gno collection list
gno collection list --json

gno collection remove

Remove a collection.

gno collection remove notes

gno collection rename

Rename a collection.

gno collection rename notes work-notes

Indexing Commands

gno update

Sync files from disk into the index (BM25/FTS only, no embeddings). Incremental - only processes files changed since last sync.

gno update
gno update --git-pull       # Pull git repos first

Options:

• --git-pull - Run git pull in git repositories

Use gno update when you only need keyword search, or when you want to quickly sync changes and run gno embed separately.

gno index

Full index end-to-end: runs gno update then gno embed. This is the recommended command for most users.

gno index                   # Index all collections
gno index notes             # Index specific collection
gno index --no-embed        # Skip embedding (same as gno update)
gno index --git-pull        # Pull git repos first

Options:

• --collection <name> - Scope to single collection
• --no-embed - Skip embedding phase
• --models-pull - Download models if missing
• --git-pull - Run git pull in git repositories

Incremental: Both gno index and gno update are incremental. Files are tracked by SHA-256 hash. Only new or modified files are processed. Unchanged files are skipped instantly.

gno embed

Generate embeddings for indexed chunks.

gno embed
gno embed notes

Context Commands

Contexts add semantic hints to improve search relevance.

gno context add

gno context add "/" "Global search context"
gno context add "notes:" "Personal notes and journal entries"
gno context add "gno://notes/projects" "Active project documentation"

gno context list

gno context list

gno context check

Validate context configuration.

gno context check

gno context rm

gno context rm "/"

Model Commands

gno models list

List available and cached models.

gno models list
gno models list --json

gno models use

Switch model preset. Changes take effect on next search.

gno models use slim       # Default, fast, ~1GB disk
gno models use balanced   # Larger model, ~2GB disk
gno models use quality    # Best answers, ~2.5GB disk

gno models pull

Download models.

gno models pull --all
gno models pull --embed
gno models pull --rerank
gno models pull --gen
gno models pull --force   # Re-download even if cached

gno models clear

Remove cached models.

gno models clear

gno models path

Show model cache directory.

gno models path

Skill Commands

Install GNO as a skill for AI coding assistants (Claude Code, Codex).

gno skill install

Install the GNO skill files.

gno skill install                    # Project scope, Claude target
gno skill install --scope user       # User-wide installation
gno skill install --target codex     # For Codex instead of Claude
gno skill install --target all       # Both Claude and Codex
gno skill install --force            # Overwrite existing

Options:

• --scope <project|user> - Installation scope (default: project)
• --target <claude|codex|all> - Target agent (default: claude)
• --force - Overwrite existing installation

gno skill uninstall

Remove installed skill.

gno skill uninstall
gno skill uninstall --scope user
gno skill uninstall --target all

Options:

• -s, --scope <project|user> - Scope to uninstall from (default: project)
• -t, --target <claude|codex|all> - Target to uninstall from (default: claude)

gno skill show

Preview skill files without installing.

gno skill show
gno skill show --file SKILL.md
gno skill show --all

Options:

• --file <name> - Show specific file only
• --all - Show all skill files

gno skill paths

Show installation paths for all scope/target combinations.

gno skill paths
gno skill paths --json

See Using GNO with AI Agents for setup guide.

Tag Commands

Manage document tags. Tags are extracted from markdown frontmatter during sync.

Tag format: lowercase alphanumeric, hyphens, dots, slashes for hierarchy (e.g., project/web, status.active).

gno tags

List all tags with document counts.

gno tags                    # All tags
gno tags --collection notes # Tags in collection
gno tags --json

gno tags add

Add tag(s) to a document.

gno tags add abc123 work
gno tags add abc123 project/alpha urgent

gno tags rm

Remove tag(s) from a document.

gno tags rm abc123 obsolete
gno tags rm abc123 draft wip

Tag changes update the document’s YAML frontmatter on disk.

Link Commands

Navigate document relationships via wiki links and markdown links.

gno links

List outgoing links from a document.

gno links gno://notes/source.md        # List all links
gno links #abc123 --type wiki          # Wiki links only
gno links source.md --json

Options:

• --type <wiki|markdown> - Filter by link type
• --json, --md - Output format

Shows link type, target, display text, line/column, and whether the target resolves to an indexed document.

gno backlinks

List documents that link TO a target document.

gno backlinks gno://notes/target.md
gno backlinks #abc123 --collection notes
gno backlinks target.md --json

Options:

• -c, --collection <name> - Filter by source collection
• --json, --md - Output format

gno similar

Find semantically similar documents using vector embeddings.

gno similar gno://notes/note.md
gno similar #abc123 --limit 10 --threshold 0.5
gno similar doc.md --cross-collection --json

Options:

• -n, --limit <num> - Max results (default: 5)
• --threshold <num> - Minimum similarity (default: 0.7)
• --cross-collection - Search across all collections
• --json, --md - Output format

Requirements: Embeddings must be generated with gno embed or gno index. Similarity basis: Uses the doc’s seq=0 embedding (falls back to first chunk).

gno graph

Export knowledge graph of document links (wiki links, markdown links, similarity edges).

gno graph                           # JSON output (default)
gno graph --dot                     # Graphviz DOT format
gno graph --mermaid                 # Mermaid diagram format
gno graph -c notes                  # Single collection
gno graph --include-similar         # Add similarity edges

Options:

• -c, --collection <name> - Filter to single collection
• --limit <n> - Max nodes (default: 2000)
• --edge-limit <n> - Max edges (default: 10000)
• --include-similar - Include similarity edges
• --threshold <num> - Similarity threshold (default: 0.7)
• --include-isolated - Include nodes with no links
• --similar-top-k <n> - Similar docs per node (default: 5)
• --json - JSON output (default)
• --dot - Graphviz DOT format
• --mermaid - Mermaid diagram format

Pipeline to Graphviz:

gno graph --dot | dot -Tsvg > graph.svg

Pipeline to Mermaid Live:

gno graph --mermaid | pbcopy
# Paste into https://mermaid.live

Similarity edges use seq=0 embeddings only.

Admin Commands

gno status

Show index status.

gno status
gno status --json

gno doctor

Check system health.

gno doctor
gno doctor --json

gno cleanup

Remove orphaned content.

gno cleanup

gno reset

Reset to fresh state.

gno reset --confirm

gno vec

Vector index maintenance. Use when vector search returns empty despite embeddings existing.

gno vec sync      # Sync vec0 index with content_vectors
gno vec rebuild   # Full rebuild of vec0 index

• sync - Fast incremental sync, fixes drift after failed inserts
• rebuild - Full rebuild, use when sync isn’t enough
• --json - JSON output format

When to use: If gno similar returns empty results but embeddings exist, run gno vec sync.

Output Formats

Example:

# Get file URIs for piping
gno search "important" --files | xargs gno get

# Parse JSON in scripts
gno search "test" --json | jq '.results[].uri'

Exit Codes

Web UI

gno serve

Start a local web server for visual search and document browsing.

gno serve
gno serve --port 8080

Options:

• -p, --port <num> - Port to listen on (default: 3000)

Features:

• Dashboard (/) - Index stats, collection overview, health status
• Search (/search) - Full-text BM25 search with highlighted snippets
• Browse (/browse) - Collection and document list with filtering
• Document View (/doc) - Rendered document content with syntax highlighting

API Endpoints:

• GET /api/health - Health check
• GET /api/status - Index status (documents, chunks, collections)
• GET /api/collections - List collections
• GET /api/docs - List documents (paginated: ?limit=20&offset=0&collection=name)
• GET /api/doc - Get document content (?uri=gno://collection/path)
• POST /api/search - Search ({"query": "...", "limit": 10})

Security:

• Binds to 127.0.0.1 only (no LAN exposure)
• Content Security Policy headers
• CSRF protection for mutations
• DNS rebinding protection

Example:

# Start server
gno serve --port 3001

# Open in browser
open http://localhost:3001

Shell Completion

Enable tab completion for gno commands.

Install Automatically

gno completion install

Auto-detects your shell and installs to the appropriate config file.

Manual Installation

# Bash (add to ~/.bashrc)
gno completion bash >> ~/.bashrc

# Zsh (add to ~/.zshrc)
gno completion zsh >> ~/.zshrc

# Fish
gno completion fish > ~/.config/fish/completions/gno.fish

Restart your shell or source the config file to activate.

Completion Features

• Commands and subcommands
• All flags and options
• Collection names (dynamic, when DB available)

MCP Server

Start MCP server for AI assistant integration.

gno mcp

See MCP Integration for setup details.