Install the Bun CLI package.

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

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 runtime state through an additive, cross-process lock-safe path; the tracked profile is not modified, and unrelated collections or indexed documents are not deleted. 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. Semantic identity is stable across timestamps, stage tokens, and created/reused disposition, but changes with material folder, index, or activation evidence.

One live one-shot worker owns its canonical job and PID until exit; reruns cannot replace it. --no-semantic starts none, preserves a previous live owner, and records skipped intent rather than completed work. Pending or failed state keeps lexical success and includes an exact foreground gno ... embed <collection> resume command.

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.

Setup is direct: it never attaches to serve, daemon, Web, or MCP. Web/Desktop onboarding instead hands work to resident collection, sync, model, and connector APIs. It shares retrieval-proof semantics but does not proxy the CLI transaction or produce its private setup receipts.

The Web Health Center, /api/status.activation, doctor, and status consume one readiness contract. /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.