Install GNO

CLI commands

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

The gno CLI indexes local folders into SQLite and runs BM25, vector, hybrid, and cited Ask against that index. 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.

How the CLI thinks

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

Setup: verified first retrieval

gno setup

Creates or reuses a collection, indexes it, and succeeds only after an exact gno:// result. Semantic indexing runs in an independent one-shot process; --no-semantic records a truthful skip. Direct setup never attaches to a resident process.

gno setup ~/notes --name notes
gno setup ~/notes --name notes --exclude .env --exclude private
gno setup ~/notes --authorize-secret-risk
gno setup ~/notes --no-semantic
gno setup . --apply-profile --no-semantic
gno setup ~/notes --connector cursor-mcp --connector codex-skill

--exclude is one repeatable literal pattern, not a CSV. Secret-risk detection fails closed; only interactive confirmation or --authorize-secret-risk authorizes likely credentials. Safe-default --yes, JSON, non-TTY, decline, and EOF do not. Exit 0 means lexical proof completed, even when semantic or connector follow-up remains. Exit 1 is invalid or safely rejected input. Exit 2 is config, receipt, I/O, store, indexing, proof, or invariant failure.

Canonical private state lives under the configured data directory at setup-receipts/<index>/<folder-fingerprint>.json and setup-semantic/<index>/<folder-fingerprint>.json. The lexical receipt is closed before semantic work starts. Semantic identity ignores timestamps, stage tokens, and created/reused disposition, but changes with material folder, index, or activation evidence.

One live semantic worker owns that canonical job and PID until exit; reruns cannot replace it, even when options change. --no-semantic starts no worker, preserves any live owner, and records skipped intent rather than completed work. Pending or failed receipts keep lexical exit 0 and print an exact foreground gno ... embed <collection> resume command.

Setup checks for the nearest valid .gno/index.yml. By default it only prints an advisory and points to gno profile diff; it does not mutate profile-owned config. Pass --apply-profile to apply a valid profile before lexical setup. For a valid profile, that option cannot be combined with explicit --name or --exclude; conflicting input fails before config or index mutation. A missing or invalid profile never makes setup mandatory: normal setup continues, while an explicitly requested apply is reported as a truthful follow-up action. Inspection transport failures abort before apply; failed, incomplete, or unresolvable apply results abort before ordinary setup and connector work. A late apply failure may leave resumable create/update-only state.

Without connectors or profile application, JSON is setup-command-result@1.0. Connector mode uses setup-activation-result@1.0 around the unchanged setup result. With --apply-profile, the closed setup-profile-result@1.0 records the profile check, optional apply, setup result, and any connector results. Supported connector IDs: claude-code-skill, claude-desktop-mcp, cursor-mcp, codex-skill, opencode-skill, openclaw-skill, and hermes-skill. Skill execution remains target_runtime_unverifiable; connector follow-up may be completed_with_actions with lexical success intact.

Web and Desktop onboarding deliberately use resident collection, sync, model, and connector APIs. They share the lexical-proof semantics but do not proxy this CLI transaction and do not produce or claim its private setup receipts.

Project profiles: check, show, diff, apply

These commands discover the nearest repository-owned .gno/index.yml. Discovery stops at the first Git root, filesystem boundary, or filesystem root; a nearer nested profile shadows, rather than merges with, an ancestor profile. Passing a directory or its exact .gno/index.yml disables ancestor fallback.

gno profile check [path]
gno profile show [path]
gno profile diff [path]
gno profile apply [path]

Add --json for deterministic, path-redacted closed contracts: project-profile-command@1.0 for check, show, and diff; project-profile-apply@1.0 for apply. Unknown output fields are not part of either contract. Apply is idempotent and interruption-safe; every config writer reloads and writes through one canonical target-derived cross-process lock, including symlink aliases (including dangling aliases). Local profile provenance keeps repeated apply byte-stable while detecting removal-only edits. Public receipts identify the collection but redact the local profile path, and the apply receipt stays outside the project. Config, data, databases, cache, selected file-backed models, receipts, and locks may not overlap the project root. Apply fails before mutation when that runtime boundary is unsafe. It never writes the tracked profile or indexes documents.

Advanced 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/**"

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
gno index --lock-wait 5m

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

Structured --json results include results[].source.absPath when the hit is a resolvable file-backed document. There is no --source flag. If absPath is absent, show the URI tail and do not offer file-open for that row.

Default snippets skip a leading YAML frontmatter fence and prefer document prose. When the FTS window is frontmatter-dominated, GNO falls back to stripped chunk prose. line and snippetRange.startLine follow that trimmed display range. --full and --line-numbers still emit the raw source. This display cleaning applies to gno search, gno vsearch, and gno query.

Local CLI retrieval uses the canonical repository or worktree for the current directory as a bounded soft signal. When the nearest local .gno/index.yml is valid, its canonical root and affinity defaults replace that cwd-derived fallback for the request; the profile does not mutate the user’s global affinity config. A matching collection can receive at most +0.03. Pass repeatable --project-root <path> values to replace the profile or cwd-derived root. The user config’s projectAffinity.enabled setting controls only cwd fallback; explicit roots and valid profiles retain their higher precedence. Use --no-project-affinity to disable every source for one request. Invalid and missing profiles fall back normally. Roots never stack; collection, tag, date, exclude, and egress filters stay hard. Explain output exposes only redacted collection and root aliases. Trusted local diagnose uses a closed schemaVersion: "1.1" response with required redacted affinity metadata, including project_profile as the source when the profile supplied the request-local root, and unmatched state. Absent, disabled, and remote/untrusted diagnose requests keep exact legacy v1.0 bytes and omit affinity.

gno query

Hybrid retrieval for normal use. It combines keyword, vector, fusion, default bounded graph expansion, and optional reranking. Disable the graph stage only when you explicitly want a graph-free path.

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" --explain
gno query "pure vector/lexical" --no-graph
gno query $'auth flow\\nterm: "refresh token"\\nintent: token rotation'

One configured contentTypes[].searchBoost may contribute at most ±0.05 and composes with trusted local project affinity under a shared ±0.08 cap. BM25 and vector only adjust candidates that already survived retrieval and minScore. Hybrid adds the composed auxiliary score to normalized fusion before rerank blending, so rerank order and lexical top-hit protection remain authoritative. The signal cannot create a candidate or bypass hard filters. --explain reports the base score, factor, bounded contribution, final score, rule source, and ranking fingerprint when active.

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 "who owns the launch decision?" --verify
gno ask "summarize my latest meeting notes" --since "last week"
gno ask "what did I save about local-first apps?" --show-sources

Context Capsules and saved freshness

Compile one deterministic, token-budgeted evidence bundle, verify a saved bundle without rebuilding it, or explicitly register a caller-owned Capsule file for resident freshness checks:

gno context build "compare launch proposals" --budget 12000 --json --output capsule.json
gno context verify capsule.json --json
gno context watch capsule.json --question "Who owns launch?" --notify --json
gno context watches --json
gno context reverify <registration-id> --json
gno context unwatch <registration-id>

Watch lifecycle commands are CLI-only and scoped to the Capsule's canonical index. GNO stores bounded metadata and evidence hashes—not Capsule or passage bytes—and never rewrites the saved file. Completed work stores the same canonical, non-generative verification receipt; a failed operation has no receipt. Manual reverification still renders that structured failure, including its code and message, then exits nonzero so scripts cannot mistake it for a successful receipt. Local notifications contain only registration/Capsule identity, operation status, affected-question state, and timestamp.

Knowledge Delta

Read bounded metadata-only change history, one retained structural diff, or explainable inbound dependency paths:

gno changes --since 2026-07-20T00:00:00Z --json
gno diff gno://notes/plan.md --json
gno impact gno://notes/plan.md --max-depth 3 --max-edges 250 --json

Change IDs and cursors are opaque. Journal retention can expire old cursors; GNO reports partial, expired, or unavailable history instead of reconstructing source bodies. Impact traversal always enforces depth, node, edge, frontier, and visited-row bounds.

Private retrieval receipts

With retrievalTraces.enabled: true, successful search, query, ask, get, and Context Capsule calls print Trace: <traceId> to stderr. Stdout and structured payloads remain unchanged. Continue a retrieval-only receipt by passing the ID to an exact read:

gno query "deployment decision"
gno get gno://work/decisions/deploy.md --from 40 --limit 20 --trace-id <traceId>

Terminal replay-mode receipts with explicit labels can become content-free qrels and a verified local replay baseline:

gno trace export <traceId> --format qrels --output qrels.json
gno trace replay <qrels-export-id> --candidate hybrid --md

Replay checks the aggregate manifest and immutable evidence hashes, then compares rank, coverage, capability fallbacks, and source freshness. It can recommend promotion but always returns applied: false; it never edits ranking configuration, models, prompts, traces, or source files.

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.

Structured search, vector, query, and ask results may also include context: user-configured guidance resolved for that exact uri and docid. Matching guidance composes global first, collection second, then path prefixes from broadest to most specific. It guides interpretation without changing ranking.

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

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.

Doctor and status also expose collection-scoped retrieval activation. Lexical readiness comes from a corpus-derived local search that must return the expected indexed document; it does not wait for semantic models. Semantic state is reported independently and may remain pending or skipped. Connector rows come only from fingerprint-current receipts created by the explicit Web connector verification action. If the bounded connector projection is truncated, omitted target/collection pairs have no result and overall connector health remains non-green.

gno peek

Cheap read-only snapshot of index counts, backlog, recent files, and whether detached serve is up. One invocation; no model or embedding initialization. Use it instead of composing gno status + gno ls + gno changes. Keep gno status for activation, onboarding, and the full health payload. Status bars and desktop widgets can poll it on a coarse interval. GNO Recall (omarchy plugin add https://github.com/gmickel/omarchy-gno-recall) uses this snapshot from the Omarchy bar.

gno peek
gno peek --json

Uninitialized is success: --json returns initialized: false with pinned nulls and recent: [], exit 0. JSON is peek@1.0. recent is at most 10 files, newest first. recent[].absPath is the path to open a recent file without gno get. serve.running is pid-file based and is true only for gno serve --detach. A foreground gno serve is not detected. A stale pid reports not running. There is no HTTP probe. Any subquery failure is an atomic RUNTIME envelope (exit 2). Peek never emits a half-filled snapshot.

{
  "schemaVersion": "peek@1.0",
  "initialized": true,
  "counts": { "documents": 1234, "collections": 5 },
  "backlog": { "pending": 0, "failed": 0 },
  "lastIndexedAt": "2026-08-29T09:00:00Z",
  "recent": [
    {
      "docid": "#abc123",
      "uri": "gno://notes/inbox.md",
      "title": "Inbox",
      "collection": "notes",
      "absPath": "/home/user/notes/inbox.md",
      "modifiedAt": "2026-08-29T08:55:00Z"
    }
  ],
  "serve": { "running": true, "url": "http://localhost:3000" }
}

When serve.running is true, open a document in the Web UI with the frozen template {serveUrl}/doc?uri=<encodeURIComponent(uri)> (serve.url plus document URI; optional #anchor). See document deep links.

gno capture

Capture writes a note into an editable collection. Inline content,--stdin, and --file are mutually exclusive. Capture accepts text only; binary-like file or stdin content is rejected before writing. With no path, folder, or title, captures land under inbox/YYYY-MM-DD/capture-<body-hash>.md using UTC time.

gno capture "thought to remember"
gno capture --stdin --collection notes --preset source-summary --tags inbox,gno
gno capture --file ./clip.md --source-url https://example.com --source-kind web --json
gno capture --preset person --title "Jane Doe" --folder people/
gno capture --preset meeting --title "Weekly sync" --folder meetings/
gno capture "meeting note" --quiet

Preset IDs include blank, project-note, research-note, decision-note, prompt-pattern, source-summary, idea-original, person, company-project, and meeting. The typed second-brain presets keep current synthesis above ## Timeline and dated evidence below it.

JSON output returns a receipt with separate write, sync, and embed status. Capture syncs the note into text search; it does not imply embedding unless embed.status is completed. Capture writes fail instead of replacing a late-arriving file.

Relationships: links, backlinks, similar, graph

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

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. Default serve is the production bundle; --dev enables the development bundle with HMR.

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

gno daemon

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

Exact eligible file events always use content-hash synchronization. Atomic-save temp names, directory events, missing filenames, and recursive deletions use bounded filesystem/index reconciliation with durable retries. Only proven candidates and removals are applied; unsupported anchored handles or bounded overflow safely escalate to full collection sync. These guarantees cover supported local filesystems, not every network or removable volume.

The resident also coalesces settled document-journal changes and reverifies affected saved Context Capsules in one bounded serial drain. Its durable high-water mark prevents duplicate work after restart; cursor expiry triggers one conservative bounded pass. Reverification writes no source or Capsule files and invokes no answer-generation model.

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. Serve and daemon are alternative owners of one resident index: a second process against the same data directory is rejected.

Agents, models, publishing, and maintenance

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.

Long terminal output honors $PAGER. Without an override, GNO uses less -R on Unix and a built-in less-compatible pager on Windows, including backward scrolling and search. Use --no-pager for automation or direct output.