glyphdown

name

glyphdown

description

Collaborate on Glyphdown docs and files (Google Docs for markdown) via the glyphdown CLI. Use when users ask to edit my glyphdown docs, sync my markdown notes, pull my notes, push this writeup, upload a file/image/HTML asset and get its link, list a folder's files, leave suggestions on the doc, comment on a doc, share a doc with a public link, clone my glyphdown workspace, or any markdown collaboration with glyphdown.com docs. Trigger phrases include "glyphdown", "sync my notes", "pull the doc", "push my edits", "add this file to glyphdown", "upload this html/image", "get the link for", "suggest changes on the doc", "check comments on the doc", "share the doc", "make a public link".

Glyphdown

CLI for collaborating on Glyphdown markdown docs. Humans edit live in the web UI; you edit plain .md files and the server CRDT-merges, so concurrent human work survives — as long as you follow the rules below.

Full reference: docs/agent-guide.md (works from the repo or a CLI-installed copy).

Auth

export GLYPHDOWN_API_KEY=gd_sk_... (minted in Settings → Agents) or glyphdown login --key gd_sk_.... Server defaults to https://glyphdown.com; override with GLYPHDOWN_SERVER or --server.

Core loop

glyphdown clone work && cd work   # once; mirrors every folder/doc you can access (default dir: ./glyphdown)
# ... edit .md files, add images/HTML assets, mkdir new folders — normal tools ...
glyphdown sync                    # two-way reconcile, run before AND after editing

sync operates on the cwd — run it inside the workspace (or pass the dir: glyphdown sync work).

Vaults: every doc lives in one vault (an Obsidian-style root namespace; a full clone shows vaults as top-level dirs). glyphdown vaults --json lists yours; glyphdown clone --vault <name|id> makes a workspace confined to one vault (clone and sync both ignore everything outside it); glyphdown new <name> --vault <vault> creates at its top level. Vault names resolve case-insensitively; with neither --vault nor --folder, new lands in the key owner's default vault.

Sync prints one action per doc/folder: pushed / pulled / merged / created (new local file → new doc) / new (new server doc) / folder created / new folder (server) / renamed locally: old → new / local missing — re-pulled / remote gone / up to date.

Exit codes (always check): 0 clean · 2 failed hunks — printed like git .rej; re-apply those edits by hand and sync again · 3 degenerate skip — your change rewrites most of a doc that drifted; re-pull and redo, or --force ONLY if the rewrite is intentional — never blind --force on a shared doc · 1 anything else (read stderr).

Single docs without a clone: glyphdown pull <id|url> → edit → glyphdown push <file>.

Files (docs and assets, same verbs)

Docs (.md, collaborative CRDT) and other files (images/.html, opaque blobs — last-write-wins, no merge) share one CLI surface; the verbs dispatch by file type. No clone needed to add one file:

glyphdown add report.html                  # upload one file → prints its viewer URL (lands in your default vault)
glyphdown add chart.png --folder Research  # target a folder/vault; --vault and --doc also work
glyphdown add notes.md                     # a .md is created as a DOC with the file's content, in one step
glyphdown ls --folder Research             # docs AND files in one folder
glyphdown url page.html --folder Research  # a file's URL anytime, idempotent (no re-upload)
glyphdown mv old.png new.png               # rename (server+local); a file keeps its comments/versions/share links
glyphdown rm page.html                     # delete on the server + archive the local copy

new makes an EMPTY doc; add <file.md> is create-with-content. Scope is optional (default vault) — pass --folder/--vault/--doc to target one. Outside a folder workspace, mv/rm/url/cat on a file need an explicit --folder/--doc. A doc and a file may share a name in a folder, so address a file by filename + scope (or its viewer URL), not bare.

Suggestions instead of edits

For reviewable changes: glyphdown push <file> --suggest -m "why" (or sync with a suggester-role key — pushes land as suggestions automatically). Humans accept/reject in the web UI; your local base does not advance — re-pull after review. List with glyphdown suggestions <doc> --json.

Renames

glyphdown mv <file> <new-name> — NEVER bare mv: sync does not detect renames, so the old name re-pulls and the new file becomes a duplicate doc. mv renames the local file and the server name together — for both docs and files (assets); a renamed file keeps its comments, versions, and share links.

Deletes

glyphdown rm <file> (alias: glyphdown delete <file>) deletes a tracked doc on the server, archives the local markdown file under .glyphdown/trash/docs/, and removes active tracking metadata so later syncs do not re-pull it. NEVER bare rm for an intentional doc delete: deleting the file by hand still re-pulls it on sync. It refuses if the remote changed since your local base; re-sync first or pass --force only when discarding remote edits is intentional.

Comments

glyphdown comments <doc> --json                       # open threads
glyphdown comment <doc> --body "..." [--line N]       # new (line-anchored) comment
glyphdown comment <doc> --reply <id> --body "..."     # reply
glyphdown comment <doc> --resolve <id> [--body "..."] # resolve (reply first if --body)

Share links (anyone-with-link)

Owner-only. <doc> is an id or URL; folders/vaults use --folder <id|name> instead (the link covers the whole subtree, URL /f/<folderId>?share=<token>).

glyphdown share <doc> [--role viewer|commenter|suggester|editor] [--json]  # create (default viewer); prints https://…/d/<docId>?share=<token>
glyphdown share list <doc> [--json]                   # active links: token, role, url
glyphdown share revoke <doc> <token>                  # revoke (a ?share= URL alone also works)
glyphdown share [list|revoke] --folder <ref> …        # folder/vault variants

Per-file HTML asset links (folder/vault assets only, view/comment only — suggester/editor rejected). Target by viewer URL or filename + --folder; recipient lands on /f/<folderId>/file/<filename>?share=<token>:

glyphdown share page.html --folder <ref> [--role viewer|commenter]   # create (default viewer)
glyphdown share list page.html --folder <ref> [--json]               # active per-file links
glyphdown share revoke --folder <ref> page.html <token>              # revoke — filename THEN token

The token IS the capability — treat share URLs as secrets.

Rules

• --json on read commands (list/ls, vaults, cat, url, comments, suggestions, new, add, sync, share) for parsing.
• Filenames are canonical slugs ([a-z0-9-] + .md); the file name IS the doc name everywhere. The # heading is just content.
• Don't rewrite >60% of a shared doc in one push (the server refuses with exit 3). glyphdown snapshot <doc> -m "msg" before big changes.
• Deletions never propagate implicitly: deleted local files re-pull; server-deleted docs warn (remote gone) and stay local. Use glyphdown rm <file> for intentional doc deletes; it refuses remote drift unless you pass --force.
• Never edit .glyphdown/ (the push bookkeeping). Sync sequentially — one sync at a time per workspace; pushes are rate-limited 60/min.