---
title: Share links
icon: LuShare2
description: Copy a link to any doc or folder and send it to a teammate. OpenKnowledge handles the GitHub round-trip, the deep link, and the branch on the other end.
---

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, SAML SSO blocks, and rate-limit errors all surface inline.
3. On submit, creates the repository through GitHub's API, sets it as `origin`, and runs the initial `git push`.
4. Once the push lands, copies the share URL to your clipboard automatically.

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.

## 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 the branch from which it was shared.

The splash offers two ways to receive:

- **Desktop app (macOS).** Click **Open in OpenKnowledge** 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 for macOS** ships the arm64 DMG for recipients who don't yet have the app.
- **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](/docs/reference/cli#clone-from-github) 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 falls through to a branch-switch dialog instead of silently opening the wrong content. Behavior depends on whether the shared target (file or folder) exists on your current branch:

- **Target exists on both branches.** The dialog offers `Open on <current-branch>` or `Switch to <share-branch> and open`.
- **Target only on the share's branch.** The dialog offers `Switch to <share-branch> and open` plus Cancel.

### 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, click the sync indicator to re-check; OpenKnowledge will pick up the change without an app restart. See [GitHub sync: GitHub-side blockers](/docs/features/github-sync#github-side-blockers) for the full set of permission shapes the sync UI handles.

See [GitHub sync](/docs/features/github-sync) for how to automatically sync changes to GitHub, and [Timeline and recovery](/docs/features/timeline-and-recovery) for per-doc history once the doc is open.
