Sharing and guests - Kythene docs

Four different things people mean by "share", and Kythene keeps them separate.

If you belong to several workspaces, a piece of work can be mapped into another one. It's the same collection, visible in both - not a copy, so there's no second thing to keep in step.

kythe share <collection-id> <target-space>
kythe unshare <collection-id> <target-space>

You must be a member of both. This is also the mechanism behind promoting a memory, which adds a review gate on top.

2. Invite someone to the workspace

A full member with a role - owner, admin, member or viewer. They sign in, they see the workspace, and they count towards your plan's seats if they're a signed-in human. See Workspaces, members and roles.

Use this for people who are part of the team.

A share code is a pseudo-identity scoped to one tag. Send someone the link and the code, and with no account at all they can:

view the collections carrying that tag,
comment on them, and
approve them.

Everything not carrying that tag stays invisible. Their contributions are attributed to the label you gave the code and marked as coming from outside the workspace, so your team's instances can weigh them accordingly.

Guests never consume a seat. A client approving a deliverable, or a cofounder signing off a pricing change, shouldn't need procurement.

kythe share-code <tag> --label "Acme - Jo"
kythe share-code <tag> --label "Acme - Jo" --expires-days 30 --pin 246813
kythe share-codes --tag client-acme
kythe revoke-code <share-code-id>

The link a holder opens reads https://kythene.com/v/<workspace-slug>/<tag>/c/<code> - a readable workspace slug rather than a raw id (see the slug below).

Codes can be minted with an expiry (--expires-days, or the app's dropdown), or left to run until revoked.

A share link on a wiki is the same mechanism pointed at a wiki's own access, and it's the one to reach for when the thing you're handing over is a knowledgebase rather than a deliverable. Mint it from the wiki's settings.

The holder lands on the wiki's home page at the link itself, with the contents of everything they're admitted to, and search within it that never surfaces a page they can't open. They see no drafts, no restricted sections they hold no grant for, no history and no state controls.

They can tell you something's wrong against the page they're reading, and they see only their own notes back. The label on a code is your bookkeeping ("Acme - Jo"), so it's meaningless to the person holding it and would be the wrong name over somebody else's words.

A viewer admitted by a tag password rather than a code holds no identity, so they can read but not comment, and they reach no restricted section at all.

Add a PIN for a second factor

A share code is a bearer credential: whoever holds the link is admitted. For most shares that's the point. When a pack goes to an external party's staff, add an optional PIN so a forwarded email, a screenshot or a shared laptop is not access on its own:

kythe share-code <tag> --label "Acme - Jo" --pin 246813   # at creation
kythe share-pin <share-code-id> 135790                    # add/change later, link unchanged
kythe share-pin <share-code-id> --clear                   # remove it
kythe unlock-code <share-code-id>                          # clear a brute-force lockout

The link and the PIN should travel by different channels - the link by email, the PIN by phone or text. With a PIN set, the link reaches a PIN prompt, never the content; only after the PIN does the holder get in, and their comments and approvals are still attributed to their label. Send it, or set it later, from the tag settings in the app too.

The PIN is 4-8 digits, stored hashed, and never shown again. Because a PIN is low-entropy, a code locks after a few wrong attempts - the tag settings show a locked code, and you unlock it (or rotate the PIN) in one action; the space is told when a code locks. This is per-code: locking one holder's code never affects the others.

PIN or tag password? A PIN is a second factor on one holder's code, keeping their identity; a tag password gates the whole tag for an anonymous, unattributed audience. Don't hand one code and its PIN round a group - that's what a tag password is for.

4. Password-protect a tag for anonymous viewing

Where a share code is a named guest who can also comment and approve, a tag password is plainer. Give a tag a password, hand it round, and anyone who has it can view that tag's collections in the browser - no account, no identity, no seat. The password lives on the tag, not on any one link, so it covers everything carrying that tag and changing it re-gates the lot.

Reach for it when the audience only needs to read one slice - a stakeholder watching the current state. There's no per-person attribution and nothing to comment with; when you want contributions back, use a share code instead. Internal and private-to-members tags can't take a password - private content is never anonymously shareable.

Set it in the tag's settings in the app, alongside its other access states, or from the CLI:

kythe tag password <tag> hunter2   # set or change
kythe tag password <tag> --clear   # remove

The workspace slug in a link

Every anonymous link carries a workspace slug - the readable segment in /v/<slug>/<tag>/... - derived from the workspace name and stable across a rename. It's what an external partner sees first, so it reads as a name rather than a raw id. The original id-based form keeps working too, so any link already sent stays valid.

Change the slug in the workspace settings, or from the CLI:

kythe space-slug acme-corp   # sets this workspace's slug
kythe spaces                 # lists each workspace's slug

Revoking cleanly

Revoke the code and access is cut immediately - the guest can't view the project any more, even holding the link. It's enforced server-side, including for password-protected tags, so there's no cached-credential window.

What they contributed stays: their comments and any artifacts they added remain part of the record. Only the way in is gone. That's usually what you want at the end of an engagement - the trail intact, the door shut.

Choosing between them

Outside your org, needs to see one slice and react to it, shouldn't have an account -> share code (add a PIN when a leaked link would matter).
Outside your org, needs a body of pages they can navigate and search -> share the wiki, which is a share code on the wiki.
A read-only audience for one slice, no reviewing, no per-person tracking -> password-protect the tag.
Part of the team, needs the whole workspace -> invite as a member.
Work that genuinely belongs to two of your workspaces -> share the collection.

One tag per engagement makes the first case clean: scope is obvious, and revocation is total rather than a hunt through what they might have seen.

1. Share a collection into another workspace