Install the Bun CLI package.

gno --version
gno setup ~/notes --name notes
gno status

Complete your agent setup

For a second brain or LLM wiki, give the harness both the GNO skill and the retrieval protocol. The skill teaches commands and workflows; the protocol teaches when to retrieve, which search path to use, and how to cite and maintain knowledge.

gno skill install --target claude --scope user
gno agents install --target claude
gno agents verify --target claude

Replace claude with codex, opencode, openclaw, or hermes. MCP users can keep their connector and add the protocol for a supported harness. Start a fresh session and check that the agent retrieves an indexed document and cites it. Agent setup and supported targets. CLI and Web UI users can skip this step.

Cloned a repository with .gno/index.yml? Setup checks the nearest valid project profile but leaves it read-only by default. Preview the portable collection and context changes, then opt in to applying them before lexical setup:

gno profile check
gno profile diff
gno setup . --apply-profile

A profile is never required. Missing or invalid profiles fall back to normal setup. Applying a valid profile writes only external user config and index state. It never modifies the tracked profile and never deletes unrelated collections or indexed documents. Databases, model caches, locks, receipts, and secrets do not belong in the repository. Likely secret context files are rejected, and context files are limited to regular UTF-8 files no larger than 64 KiB.

With a valid profile, --apply-profile cannot be combined with an explicit --name or --exclude; conflicts fail before config or index mutation.

--exclude accepts one literal pattern per occurrence. Likely secrets fail closed unless you accept the interactive default-No prompt or pass --authorize-secret-risk; --yes, JSON, non-terminal input, decline, and EOF never authorize that risk. Use --no-semantic to start no semantic worker.

Exit 0 means exact lexical proof completed, even when semantic or connector follow-up remains. Exit 1 is invalid or safely rejected input. Exit 2 is a config, receipt, I/O, store, indexing, proof, or internal failure.

Private lexical and semantic state lives under the configured data directory at setup-receipts/<index>/<folder-fingerprint>.json and setup-semantic/<index>/<folder-fingerprint>.json. Rerunning setup on an unchanged folder reuses the same semantic state.

Setup runs at most one background semantic job per folder, and a rerun does not start a second one. --no-semantic starts no job and leaves a running one alone. If semantic work is pending or failed, setup still reports keyword success and prints the exact foreground gno ... embed <collection> command that finishes it.

Add repeatable --connector flags and JSON output:

gno setup ~/notes --name notes --connector cursor-mcp --connector codex-skill --json

Exact IDs: claude-code-skill, claude-desktop-mcp, cursor-mcp, codex-skill, opencode-skill, openclaw-skill, and hermes-skill. Connector follow-up can report completed_with_actions without invalidating lexical success. MCP targets run a bounded retrieval proof; skill targets remain target_runtime_unverifiable because setup cannot safely execute the host agent runtime. Without connector flags, --json emits setup-command-result@1.0; with one or more, it switches to setup-activation-result@1.0.

gno setup runs on its own and never connects to a running gno serve, gno daemon, or MCP server. Onboarding in the Web UI and desktop app runs the same retrieval check through the running server, but it does not write the setup receipt files.

The Web Health Center, /api/status.activation, doctor, and status report the same readiness state. /api/health is process liveness only. For MCP, use the explicit read-only verification action on the Web Connectors page; installed skill runtimes remain unverifiable rather than being reported as passed.

gno mcp install records the exact Bun + installed GNO runtime, active index, and absolute config, data, and cache roots in the client configuration. That keeps desktop and editor processes on the same local workspace even when their shell environment orPATH differs.