Share links

OpenKnowledge has a Share button in the editor toolbar. Click it and the app copies a https://openknowledge.ai/d/… URL to your clipboard. Anyone you send it to lands on a splash page that knows the project and target, and a single click opens it in their copy of OpenKnowledge.

Sending a share link

Click the Share button to copy a deep link to the current doc or folder to your clipboard. The sharing functionality is backed by GitHub and requires that your project has a remote origin.

Without a remote

If the project has no origin configured, the Share button opens the Publish to GitHub wizard. The wizard:

1. Lists the GitHub accounts and orgs you can push to.
2. Validates the repo name as you type; name collisions surface inline.
3. On submit, creates the repository through GitHub's API, sets it as origin, and runs the initial git push. SAML SSO blocks and other GitHub errors surface as a banner.
4. Once the push lands, shows the share URL with a Copy share link button.

If the push fails after the repo was created (auth lost mid-flow, network blip), the wizard shows a Retry push affordance. The GitHub-side repo isn't recreated, only the push is retried.

Freshness warnings

A share link points at GitHub, but your local edits only reach GitHub through auto-sync (off by default) or a manual push. When you click Share, OpenKnowledge checks the shared doc or folder against its last-known state on GitHub and, if the link won't yet show what you're looking at, adds a non-blocking warning row to the popover:

• Not on GitHub yet. The target has never been pushed, so the link won't resolve until it is. With auto-sync off, the row offers Enable auto-sync and How to push manually; with auto-sync on, it offers Sync now and clears itself once the push lands.
• Unpushed changes. The target is on GitHub but has local edits that aren't, so recipients see the last pushed version. With auto-sync on this stays silent — the next sync closes the gap.

If you don't have write access to the repo, the row explains that instead of offering a push action. The check is local, adds no network round-trip, and never blocks sharing: if it can't run, the link still copies with no warning. Folder shares get the same treatment as docs. Links minted by an agent get the same check: the share_link MCP tool prepends the warning to its response so the agent can relay it with the link.

Opening a share link

The recipient clicks the URL and lands on a splash page showing the target (file or folder) name, the owner/repo path, and — for shares from a non-default branch — the branch name.

The splash offers two ways to receive:

• Desktop app (macOS). Click Open in macOS app to fire the deep link into the OpenKnowledge desktop app — on the shared doc, folder overview, or project root depending on what was shared. Download the app ships the arm64 DMG for recipients who don't yet have the app; the download remembers the share (a first-party cookie, valid for seven days), and the app opens the shared target on its first launch.
• CLI (macOS and Linux). Copy the pre-filled npm install -g @inkeep/open-knowledge then ok clone <owner/repo> -b <branch> from the splash to clone the repo locally and open the editor. The clone command is always branch-pinned, but if the feature branch has been deleted, it will fall back to the default branch. See the CLI reference for ok clone and related commands.

What the desktop app does when it receives the link

The deep link arrives at the desktop app's handler, which runs a three-question receive flow:

1. Q1: Do you already have this repo? The app scans recent projects for one whose gitRemoteUrl matches the share's owner/repo. A hit silently routes to that project (no dialog, the window just opens and navigates to the shared doc, folder, or project root).
2. Q2: Clone or locate? If Q1 misses, a dialog asks "Clone to a new folder" or "I already have it locally". The locate path lets you point at an existing folder.
3. Q3: Clone. On the clone path, the app runs an auth check, asks where to put the folder, then runs git clone -b <share-branch> so the new checkout lands on the right branch before opening.

Receiving on a different branch

If you have the repo open locally but on a different branch, the app opens a branch-switch dialog instead of silently showing the wrong content. It compares the shared target (file or folder) against your current branch and against GitHub, then offers the action that matches what it finds:

• On your current branch. Open it where you are, or switch to the share's branch and open.
• Not local yet, but on GitHub (your local copy is behind). Switch and update branch fast-forwards your local branch to GitHub's tip and opens the doc. This is fast-forward-only — the receive flow never merges. A branch that has diverged from GitHub instead gets a plain switch with a note that the doc will appear once the branch syncs.
• Moved. If GitHub shows the target was renamed, the dialog offers to open it at its new path.
• Removed, or never pushed. A deleted target is messaged as removed from the branch; a path that never existed on the branch is messaged as "may not have been pushed yet." The two are distinct, and neither drops you into an empty create-mode editor.

If uncommitted changes conflict with the switch, switching is disabled until you commit or stash them; if the share's branch is already checked out in another worktree, the dialog offers to open that worktree instead.

If OpenKnowledge can't reach GitHub to make this call, the dialog falls back to the plain switch; the "pull the latest changes, then open the link again" guidance appears only if the target is still missing after the switch.

When the shared target has moved or been removed

Even on the right branch, a doc or folder can be renamed or deleted after a link is minted. Rather than opening an empty editor at the old path — where you could unknowingly start a divergent copy — OpenKnowledge shows a dialog before navigating (or an in-tab panel, if the miss is only discovered after a tab opens) with the same verdict-driven copy as the branch-switch dialog: an offer to open a renamed target at its new path, a plain "removed from this branch" message with a link back to the parent folder, or "not pushed yet" when the path never existed. A target you moved, renamed, or deleted in your own local copy gets a fourth verdict: commit your changes or enable auto-sync. If the check can't reach GitHub, it falls back to the usual pull-and-retry guidance.

Receiving without push permission

If the shared repo is one your GitHub account can't push to (you're not a collaborator on a public repo, or you have read-only access on a private one), OpenKnowledge skips the usual "Enable auto-sync?" prompt. Sync is also disabled for the same reason in Settings → Sync. If the project owner grants you write access later, push permission is re-checked the next time the project's server starts. See GitHub sync: GitHub-side blockers for the full set of permission shapes the sync UI handles.

See GitHub sync for how to automatically sync changes to GitHub, and Timeline and recovery for per-doc history once the doc is open.