ShareMyMarkdown

CLI-first collaborative Markdown with realtime editing, stable share links, readable history, and draft-style revision workflows.

If you are an agent or operator landing in this repo, the practical rule is simple:

• use the CLI first
• use MCP when you need tool access from an editor or agent runtime
• use the web app for reading, live collaboration, sharing, and review

Canonical agent guidance lives in AGENTS.md. CLAUDE.md, CODEX.md, and CURSOR.md are symlinks to that file.

What To Do With This Product

Use ShareMyMarkdown when you want to:

• turn local Markdown into a durable share link instead of pasting drafts around
• write Markdown collaboratively without giving up plain text
• control whether a document is private, unlisted, or public
• keep explicit versions for meaningful checkpoints
• create isolated revisions before changing the live document
• let agents interact with the same document system through MCP

The product is designed so the same core actions exist across:

• CLI
• MCP
• web

Quick Start

Install dependencies:

bun install

Set up your environment:

cp .env.example .env

Add these values to .env:

DATABASE_URL=libsql://...
TURSO_TOKEN=...
BETTER_AUTH_SECRET=...
BETTER_AUTH_URL=http://localhost:3000
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...

For local GitHub auth, use this callback URL in your GitHub OAuth app:

http://localhost:3000/api/auth/callback/github

Start the app:

bun dev

Then open:

http://localhost:3000

Local CLI during repo development:

bun run cli -- help

Prepare the lean npm CLI package locally:

bun run build:cli-package
cd dist-cli
npm pack --dry-run

Published CLI shape:

bunx sharemymarkdown share draft.md --visibility unlisted
bun add -g sharemymarkdown
smm share draft.md --visibility unlisted

First Useful Commands

Sign in from the CLI:

sharemymarkdown auth login

Create a link from a file or stdin:

sharemymarkdown share draft.md --visibility unlisted
cat draft.md | smm share --title "Working Draft"

Open and edit an existing document:

sharemymarkdown docs get <document-id>
sharemymarkdown docs edit <document-id>
sharemymarkdown docs visibility <document-id> public

Save a version:

sharemymarkdown versions save <document-id> "Initial checkpoint"

Create and review a revision:

sharemymarkdown revisions create <document-id> "Alternative draft"
sharemymarkdown revisions edit <document-id> <revision-id>
sharemymarkdown revisions diff <document-id> <revision-id> live
sharemymarkdown revisions apply <document-id> <revision-id>

Set a default visibility for future shares:

sharemymarkdown config set default-visibility unlisted
sharemymarkdown config show

See all CLI commands:

sharemymarkdown help

MCP

There are two MCP entrypoints:

• local stdio: bun run mcp
• HTTP: http://localhost:3000/mcp

Discovery endpoints:

• http://localhost:3000/.well-known/oauth-authorization-server
• http://localhost:3000/.well-known/oauth-protected-resource
• http://localhost:3000/llms.txt

Markdown-Friendly Output

Agents should prefer markdown output when reading content.

Key GET endpoints support markdown when you send either:

• Accept: text/markdown
• ?format=markdown
• ?format=md

High-value endpoints:

• /api/documents
• /api/documents/:id
• /api/shared/:shareId
• /api/documents/:id/presence
• /api/documents/:id/versions
• /api/documents/:id/revisions
• /api/documents/:id/revisions/:revisionId
• /api/documents/:id/diff
• /api/documents/:id/revisions/:revisionId/diff
• /api/documents/:id/members

Configuration Notes

• GitHub is the first auth provider.
• Use one GitHub OAuth app for local and a separate one for production.
• CLI defaults live in ~/.config/sharemymarkdown/config.json.
• The repo workspace package is private; npm publishing happens from the generated dist-cli/ package.
• db:push can hit Turso transaction issues when it tries to recreate existing auth tables. The app also runs ensureDatabase() on startup to create missing tables safely.

Reference

• Agent instructions: AGENTS.md
• Architecture blueprint: docs/architecture.md