Reference

CLI commands

Reference for every gno command, global option, retrieval mode, background service, and integration surface.

The gno CLI is the local control plane for your knowledge base. Use it to connect folders, build the index, search and ask questions, keep the collection fresh in the background, and wire GNO into AI tools. It is useful from a terminal, but the same commands also power the Web UI, REST API, MCP server, and agent skills.

Quick chooser

Start here when you know what you want to do but not which command to reach for.

gno init, gno collection, gno index — connect folders and build the index.
gno search, gno vsearch, gno query, gno ask — retrieve knowledge.
gno get, gno multi-get, gno ls — inspect indexed documents.
gno links, gno backlinks, gno similar, gno graph — follow relationships.
gno serve, gno daemon — run long-lived local services.
gno mcp, gno skill, gno publish — connect agents and share snapshots.

How the CLI thinks

Collections point at folders on disk: notes, research, PDFs, project docs, client files, or a Karpathy-style personal knowledge base.
Indexing reads files, extracts text, chunks documents, records links and tags, then embeds chunks for semantic search.
Retrieval searches with keyword, vector, hybrid, optional graph expansion, and optional reranking.
Surfaces expose the same index through the CLI, browser workspace, REST API, MCP, SDK, and installed skills.

Setup: init, collection, index

gno init

Creates the first GNO config and points it at a folder. Use it for the first folder in a new index.

gno init ~/Documents/Knowledge --name knowledge
gno init ~/Notes --name notes --pattern "**/*.md"
gno init ~/Research --name research --exclude "**/archive/**"

--name sets the collection name used by filters.
--pattern, --include, and --exclude decide which files enter the index.
--update records a collection-specific update command, useful for git-backed or generated folders.
--tokenizer and --language tune text processing for specialized collections.

gno collection

Adds, lists, renames, removes, or resets collection embeddings after the initial setup.

gno collection add ~/Downloads/Papers --name papers
gno collection list
gno collection rename papers reading
gno collection clear-embeddings notes
gno collection remove old-notes

gno index, update, embed

update scans files into SQLite. embed creates vectors for semantic search. index does both.

gno update
gno update --git-pull
gno embed notes
gno index
gno index --models-pull
gno index --no-embed

--git-pull pulls git-backed collections before scanning.
--models-pull downloads needed model files before the run.
--no-embed builds a fast keyword-only index.
gno embed and gno embed --force retry transient embedding chunk failures inside the same command run. Use --verbose when a run still fails so the sample errors and retry hint are visible.
Run gno embed after changing embedding models or after doctor reports stale vectors. If stale or mixed vectors remain, run gno embed --force for a full vector refresh.

Retrieve: search, vsearch, query, ask

gno search and gno vsearch

search is exact and fast. Use it for titles, names, quotes, filenames, error messages, and identifiers. vsearch is semantic. Use it when the right documents may use different words than your query.

gno search "spaced repetition" --collection notes
gno search "ERR_INVALID_STATE" --line-numbers
gno vsearch "notes about memory and learning loops" --limit 10

Scope with --collection, --limit, --min-score, --since, --until, --tags-any, --tags-all.
Change output with --full, --line-numbers, --json, --md, --csv, --files, --xml.

gno query

Hybrid retrieval for normal use. It combines keyword, vector, fusion, and optional reranking. Add graph expansion when linked context matters.

gno query "what did I decide about backups?"
gno query "papers about retrieval evaluation" --tags-any research
gno query "pricing notes" --fast
gno query "architecture tradeoffs" --thorough --explain
gno query "linked context" --graph --explain
gno query $'auth flow\\nterm: "refresh token"\\nintent: token rotation'

--fast lowers latency. --thorough spends more time for better recall.
--graph enables graph-neighbor candidates. --no-expand and --no-rerank disable pipeline stages for debugging or speed.
--intent, --query-mode, --candidate-limit, and --explain steer or inspect retrieval.

gno ask

Retrieves evidence and optionally asks a local model to synthesize a cited answer. Use it for questions over your notes, not for general chatbot use.

gno ask "what are my open migration risks?" --answer
gno ask "summarize my latest meeting notes" --since "last week"
gno ask "what did I save about local-first apps?" --show-sources

--answer forces synthesis. --no-answer returns retrieval results only.
--max-answer-tokens controls answer length.
--show-sources keeps citations visible.

Read: get, multi-get, ls, tags

gno get and gno multi-get

Search results return gno:// URIs, paths, doc IDs, and line anchors. Use the read commands to pull the exact source into a terminal, script, or AI prompt after retrieval.

gno get gno://notes/learning.md
gno get gno://notes/learning.md --from 40 --limit 30
gno multi-get gno://notes/a.md gno://notes/b.md --max-bytes 12000

--from and --limit fetch bounded line ranges.
--line-numbers preserves citation-friendly anchors.
--source, --json, --md, --files control output shape.

gno ls, tags, status, doctor

Use these when results look wrong. First check whether the document is indexed, then inspect tags and health.

gno ls --collection notes
gno tags
gno status --json
gno doctor

gno doctor includes an embedding-fingerprint check. In JSON output, that check carries an embeddingFingerprint object with currentFingerprint, pendingChunks, legacyChunks, mixedGroups, and groups. Warnings mean BM25 still works, but semantic results may need gno embed or gno embed --force.

Relationships: links, backlinks, similar, graph

gno links, backlinks, similar

These commands answer “what does this note point to?”, “what points back?”, and “what is semantically nearby?”.

gno links gno://notes/llm-memory.md
gno backlinks gno://notes/llm-memory.md
gno similar gno://notes/llm-memory.md --limit 8

gno graph

Builds a document graph from wiki links, markdown links, backlinks, unresolved links, and optional similarity edges. Use it to find hubs, isolated notes, communities, nearest neighbors, and paths between ideas.

gno graph --collection notes --json
gno graph --neighbors gno://notes/llm-memory.md
gno graph --from gno://notes/a.md --to gno://notes/b.md
gno graph --include-similar --threshold 0.78
gno graph --dot > graph.dot
gno graph --mermaid

Scope with --collection, --limit, --edge-limit, --include-isolated.
Add semantic edges with --include-similar, --threshold, --similar-top-k.
Explore locally with --neighbors, --direction, --from, --to, --max-depth.

Services: serve and daemon

gno serve

Starts the local browser workspace and REST API. Use it when you want visual search, browsing, graph exploration, editing, or API access.

gno serve
gno serve --port 8080
gno serve --detach
gno serve --status --json
gno serve --stop

gno daemon

Runs the headless watch/sync/embed loop. Use it when your CLI and AI tools need fresh search results but you do not need the browser open.

gno daemon --detach
gno daemon --no-sync-on-start
gno daemon --status
gno daemon --stop

Lifecycle flags for both commands: --detach, --status, --stop, --pid-file, --log-file. --json is for --status. Avoid running serve and daemon against the same index at the same time.

gno mcp and gno skill

Use MCP when you want AI clients to call GNO tools automatically. Use skills when you want explicit /gno lookups with low context overhead.

gno mcp install --target claude-desktop
gno mcp install --target cursor --scope project
gno skill install --target all --scope user --force
gno skill paths

models, publish, bench, cleanup

These are supporting commands for model files, shared artifacts, retrieval evaluation, and housekeeping.

gno models list
gno models use balanced
gno models pull
gno publish export atlas --out ~/Downloads/atlas.json
gno bench fixture.json --modes bm25,hybrid --json
gno cleanup
gno completion zsh

Global options and output flags

Global options work before the command name. Output flags are repeated on retrieval and read commands where they make sense.

--index <name> — use a named index instead of default.
--config <path> — load a specific config file.
--offline — use cached model files only.
--json, --md, --csv, --files, --xml — structured output.
--verbose, --quiet, --no-color, --no-pager, --yes — terminal and automation behavior.