CLI reference

Sign in: opens the browser to authorize this device (AgentHog-style loopback + one-time code). With only a pre-browser credentials.json on the machine it migrates that token into config.json instead, no browser — asking which workspace it should act in (or --workspace).

sharedoc login
sharedoc login --no-browser
sharedoc login --no-wait --json            # an agent: send the human the url …
sharedoc login --code sd_code_… --json     # … and redeem the code they paste back
sharedoc login --workspace brightmotion --json   # migrate credentials.json headlessly
sharedoc-dev login --host http://localhost:3273

--json{ loggedIn, apiUrl, config, verified, tokenName, projects, logins:[{workspace,workspaceId,slug,scope}], migrated?, from? } (--no-wait: { loggedIn:false, apiUrl, url, codeTtlSeconds, next })

APIGET /cli/auth → POST /api/v1/cli/exchange (migration: GET /api/v1/me)

Who and where am I: user, token, scope, workspaces, projects, server, credential source.

sharedoc whoami --json

--json{ api, source, legacy, logins:[{workspace,workspaceId,slug,user,token:{name,prefix,scope},workspaces,projects:n,error}] } (source = the file actually read, or "SHAREDOC_TOKEN env"; legacy = it was credentials.json)

APIGET /api/v1/me

Revoke the stored tokens server-side and forget them locally.

APIDELETE /api/v1/tokens/self

List your CLI tokens (name, prefix, scope, last used).

--json{ tokens:[{id,name,prefix,scope,workspaceIds,lastUsedAt,createdAt,revoked}] }

APIGET /api/v1/tokens

Revoke one token by id.

APIDELETE /api/v1/tokens/:id

Workspaces you belong to, with your role.

--json{ workspaces:[{id,slug,name,role,projects:n}] }

APIGET /api/v1/workspaces

Create a workspace, inbox and general channel. Requires an account-wide write token from Settings → CLI access.

--json{ workspace, created }

APIPOST /api/v1/workspaces

Projects across saved logins, deduplicated and sorted by slug/id. Pages default to 50; continue with --cursor and the same filters.

sharedoc projects list --workspace justin --json

--json{ projects:[{id,slug,name,workspace,role,visibility,kind,updatedAt}], nextCursor }

APIGET /api/v1/projects

Create a project. It opens on a seeded sharedoc-instructions.md; the folder to sync comes next (sync add).

sharedoc projects create "Acme Diligence" --workspace brightmotion --json

--json{ project:{id,slug,name,workspace,visibility,channel,url,seeded[]}, created, complete, seedErrors[] }

APIPOST /api/v1/projects

The statuses a doc may carry (its front-matter `status`): the workspace's list, or with --project that project's effective list — its own, or the workspace's when it inherits (`inherited: true`). Each has a key (what the file holds), a label, one of nine colours and an optional description (when to set it).

sharedoc statuses list
sharedoc statuses list --project sharedoc --json

--json{ workspace, project, field, inherited, revision, canEdit, presets:[{key,label,color,description,position}] }

APIGET /api/v1/statuses?project=|workspace=[&field=]

Add a status to the workspace's list (owner/admin) or, with --project, to that project's own list (project owner or workspace admin). A project that inherits gets its own list, starting from a copy of the workspace's.

sharedoc statuses add ready-for-agent --color purple --description "fully specified; an agent may start"
sharedoc statuses add triage --color orange --project sharedoc

--json{ workspace, project, field, inherited, revision, changed, presets, vanished:[{key,docs}] }

APIPUT /api/v1/statuses

Remove a status from a list. Docs that still say it are not rewritten: they show it as unknown (`invalid: ["unknown-status"]`), and the output says how many.

sharedoc statuses rm triage --project sharedoc

--json{ workspace, project, field, inherited, revision, changed, presets, vanished:[{key,docs}] }

APIPUT /api/v1/statuses

Rename a status key (label kept unless --label). Docs are not rewritten: ones with the old key show it as unknown until edited.

sharedoc statuses mv review ready-for-review --label "Ready for review"

--json{ workspace, project, field, inherited, revision, changed, presets, vanished:[{key,docs}] }

APIPUT /api/v1/statuses

Change a status's label, colour, description or position.

sharedoc statuses edit blocked --color red --position 0

--json{ workspace, project, field, inherited, revision, changed, presets, vanished:[{key,docs}] }

APIPUT /api/v1/statuses

Drop a project's own list so it uses the workspace's again.

sharedoc statuses inherit --project sharedoc

--json{ workspace, project, field, inherited: true, changed, presets, vanished:[{key,docs}] }

APIPUT /api/v1/statuses { project, inherit: true }

One command from a folder to a link: create a project named after the folder, push its contents once, and print a join link.

sharedoc share ~/deals/acme
sharedoc share ./brand-board --role viewer --expires 30d --json

--json{ project, pushed:{pulled,pushed,merged,conflicts}, link, url, sync }

APIPOST /api/v1/projects · PUT /api/v1/files/content · POST /api/v1/projects/:slug/share-links

Inspect IDs, access, counts and settings URL.

APIGET /api/v1/projects/:slug

Rename the display name; IDs, slugs and links stay the same.

APIPATCH /api/v1/projects/:slug

Change project access and reconcile its channel. --dry-run explains the access change.

APIPATCH /api/v1/projects/:slug

Delete a project for good: its files (archived ones too), comments, channel, members, links and history. Posts elsewhere that only carry its label stay and lose the label; members' synced folders keep their local copies. Owners and workspace admins. Requires --yes; --dry-run says what would go.

sharedoc projects delete old-experiment --dry-run
sharedoc projects delete old-experiment --yes

--json{ deleted, project, removed:{files,archivedFiles,bytes,members,threads,messages,connections}, storage:{deleted,failed} }

APIDELETE /api/v1/projects/:slug?confirm=<slug>

Delete a workspace for good: every project and file in it, its channels, DMs and messages, its members' seats and invitations. Its agents are retired, its Slack connections disconnected, and CLI tokens that only opened it are revoked. People's synced folders keep their local copies. Only the owner. Requires --yes; --dry-run says what would go.

sharedoc workspaces delete my-mistake --dry-run
sharedoc workspaces delete my-mistake --yes

--json{ deleted, workspace, removed:{projects,files,archivedFiles,bytes,members,agents,channels,messages,slackConnections}, storage:{deleted,failed}, agentsRemoved, tokensRevoked, slackDisconnected, slackRevoked }

APIDELETE /api/v1/workspaces/:slug?confirm=<slug>

Inspect IDs, access, counts and settings URL.

APIGET /api/v1/workspaces/:slug

Rename the display name; IDs, slugs and links stay the same.

APIPATCH /api/v1/workspaces/:slug

Set the workspace's icon from a PNG, JPEG or WebP (up to 2 MB; the hub crops it to a centred square), or --remove it to go back to the initials square. Owners and admins. It shows in the sidebar's workspace picker and switcher, the settings header and the CLI login page; in the web app the same people get Add an icon under General in the workspace settings, with a crop to drag and zoom.

sharedoc workspaces icon acme ./logo.png
sharedoc workspaces icon acme --remove

--json{ workspace, icon, version? }

APIPUT|DELETE /api/v1/workspaces/:slug/icon

Members of a workspace (or the explicit members of a project with --project), with each one's status. `kind` is `person` or `bot` (an agent identity).

--json{ members:[{id,name,email,kind,role,invitedBy,joinedAt,lastActiveAt,status:{emoji,text,expiresAt,paused}|null}], invites:[{id,email,role,projectRole,workspaceRole,project,invitedBy,createdAt}] }

APIGET /api/v1/members

The workspace's agents — bots an admin created so an agent can act as itself, each with a name, who controls it, whether it is paused, who may DM it, and (for admins and its owner) its tokens. --mine lists the ones you control, across workspaces.

sharedoc agents list
sharedoc agents list --mine --json

--json{ workspace, canManage, agents:[{id,name,kind:"bot",avatar,paused,dmsFrom:"owner"|"workspace",owner:{id,name,email},workspace:{id,slug,name},createdAt,tokens:[{id,name,prefix,lastUsedAt,createdAt,revoked}]}] }

APIGET /api/v1/agents?workspace=|mine=1

Create an agent (workspace owner/admin): a member of its own with the name given, controlled by you unless --owner names another member. It cannot invite, share, change settings or mint tokens; mint its first token with `agents token`. The name is how docs assign work to it (`assignee: Night shift`), so it may not contain '@' — and renaming it later leaves the docs that name it unassigned, with a warning, until someone picks again.

sharedoc agents create Night shift
sharedoc agents create "Night shift" --owner [email protected] --json

--json{ agent:{id,name,owner,workspace,paused,dmsFrom,tokens:[]} }

APIPOST /api/v1/agents

Mint a write token for an agent, bound to its workspace — shown once; pass it to the agent as SHAREDOC_TOKEN. Its calls then write as the agent (add --as-agent / --as-model there for the 'via' chip). Admins and whoever controls it.

sharedoc agents token "Night shift" --name "cron on the server" --json

--json{ token, id, prefix, name, scope:"write", agent:{id,name}, workspace }

APIPOST /api/v1/agents/:id/tokens

Revoke one of an agent's tokens. Admins and whoever controls it.

sharedoc agents revoke "Night shift" 6f1c… --yes

--json{ ok, id }

APIDELETE /api/v1/agents/:id/tokens/:tokenId

Pause an agent: every call with its tokens is refused, by name, until `agents resume`. Its seat and tokens are kept. Admins and whoever controls it.

sharedoc agents pause "Night shift"

--json{ agent }

APIPATCH /api/v1/agents/:id { paused: true }

Resume a paused agent.

sharedoc agents resume "Night shift"

--json{ agent }

APIPATCH /api/v1/agents/:id { paused: false }

Choose who may DM an agent: `owner` — only whoever controls it, the default — or `workspace`, anyone in it. Anyone else's message (or reply, or huddle) in a DM or group with it is refused by name and never reaches it — the web shows them an auto-reply instead — and their @-mentions, replies in threads it follows and doc comments post without notifying it. Another agent with the same controller always gets through. Admins and whoever controls it.

sharedoc agents dms "Night shift" workspace
sharedoc agents dms "Night shift" owner --json

--json{ agent }

APIPATCH /api/v1/agents/:id { dmsFrom }

Set an agent's profile photo from a PNG, JPEG or WebP (up to 2 MB; the hub crops it to a centred square), or --remove it to go back to the robot disc. Admins and whoever controls it. In the web app the same people get a camera button on its profile and its Agents row, with a crop to drag and zoom.

sharedoc agents photo "Night shift" ./owl.png
sharedoc agents photo "Night shift" --remove

--json{ agent, avatar, version? }

APIPUT|DELETE /api/v1/agents/:id/avatar

Delete an agent (workspace owner/admin): its tokens are revoked and it leaves the workspace and its projects; what it wrote stays, signed "<name> (removed)".

sharedoc agents rm "Night shift" --yes

--json{ ok, id, name, tokensRevoked }

APIDELETE /api/v1/agents/:id

Show your status: the emoji and text next to your name on every message and sidebar row.

sharedoc status
sharedoc status --json

--json{ status:{emoji,text,expiresAt,paused}|null }

APIGET /api/v1/me/status

Set your status. It stays until you clear it, or clears itself after --for or at --until. --pause also snoozes your notifications for as long as it lasts.

sharedoc status set "done for the day, started early" --emoji 🌅 --until eod --pause
sharedoc status set "in a meeting" --emoji :calendar: --for 1h
sharedoc status set "on vacation" --emoji 🌴 --until 2026-09-28

--json{ status:{emoji,text,expiresAt,paused}, snoozeUntil? }

APIPUT /api/v1/me/status

Clear your status. If it paused your notifications, that snooze ends too (unless you changed the snooze since).

sharedoc status clear

--json{ status:null, snoozeUntil? }

APIDELETE /api/v1/me/status

Add people who are already in the workspace to a project (the way into a private one). Someone already on it keeps their role; someone not in the workspace is refused — invite them with `members invite`. Owners and editors may add.

sharedoc members add [email protected] [email protected] --project severance-plan --role commenter
sharedoc members add [email protected] --project severance-plan --dry-run --json

--json{ project, role, added:[{id,name,email,role}], already:[{id,name,email,role}], dryRun? }

APIPOST /api/v1/projects/:slug/members

Invite people by email to the workspace, or to one project (--project, or the connected folder's). Nobody's existing role changes: results show the workspace and project role each person actually holds. A still-pending invitation comes back as `pending` and is not re-mailed — `invites resend <id>` does that.

sharedoc members invite [email protected] --project acme --project-role commenter --workspace-role guest
sharedoc members invite [email protected] --project acme --dry-run --json

--json{ workspace, project, role, workspaceRole, projectRole, dryRun?, results:[{email,kind:"added"|"already"|"invited"|"pending",workspaceRole,projectRole?,invitationId?,emailSent,emailError?}] }

APIPOST /api/v1/members/invite

Change an explicit member's role on a project (--project; the project owner, or a workspace owner/admin who can open it — a private project only its members can) or in the workspace (--workspace; owners/admins). The owner's role never changes; nobody is added.

sharedoc members role [email protected] viewer --project severance-plan
sharedoc members role [email protected] guest --workspace acme --dry-run

--json{ project|workspace, member:{id,name,email}, before, role, changed, dryRun? }

APIPATCH /api/v1/projects/:slug/members/:who · PATCH /api/v1/workspaces/:slug/members/:who

Take someone's explicit membership off a project (--project), or remove them from the workspace and every project in it (--workspace). If they can still open the project through the workspace, the result says so. The owner cannot be removed. Requires --yes.

sharedoc members remove [email protected] --project severance-plan --yes

--json{ project, member, role, removed, stillHasAccess:{role,through}|null, warning } | { workspace, member, role, removed, projects }

APIDELETE /api/v1/projects/:slug/members/:who · DELETE /api/v1/workspaces/:slug/members/:who

Pending email invitations — a project's (--project) or the workspace's — with the id `invites resend|revoke` take. (`invite links` lists share links.)

sharedoc invites list --project acme

--json{ project|workspace, invites:[{id,email,project,projectRole,workspaceRole,invitedBy,invitedById,createdAt,lastSentAt,sends,resendableAt,canManage}] }

APIGET /api/v1/invites

Mail a pending invitation again — at most once every 10 minutes and 5 times in all. Whoever sent it, the project owner, or a workspace owner/admin who can open the project. The invitation stays as it was; `delivery` says whether the mail went.

--json{ invitation, resent, delivery:{sent,error} } | { dryRun, invitation, wouldSend, blocked }

APIPOST /api/v1/invites/:id/resend

Withdraw a pending invitation so it no longer lets anyone in. Removes nobody — use `members remove`. Requires --yes.

--json{ invitation, revoked }

APIDELETE /api/v1/invites/:id

Mint a join link for a project: anyone who opens it joins with the given role (a share link, /join/<token>).

sharedoc invite link --project acme --role viewer --expires 30d
sharedoc invite link --folder clients/acme --role commenter --project deals

--json{ project, link:{id,role,label,expiresAt,revoked,lastUsedAt,createdAt}, url } | { project, path, link:{audience,role,expiresAt}, url, minted, replaced, losesAccess }

APIPOST /api/v1/projects/:slug/share-links · PUT /api/v1/resources/link (--file/--folder)

List a project's join links, revoked ones included. With --file/--folder: that path's scoped link (metadata only — secrets never appear in listings; `invite copy` returns it).

--json{ project, links:[…] } | { project, path, link:{audience,role,expiresAt,lastUsedAt}, url }

APIGET /api/v1/projects/:slug/share-links · GET /api/v1/resources/link

Revoke a join link; anyone who already joined stays. With --file/--folder: set that path to Restricted (people who joined through its link lose that access; direct grants and memberships stay).

--json{ project, link, revoked:true } | { project, path, link, losesAccess }

APIDELETE /api/v1/projects/:slug/share-links/:id · PUT /api/v1/resources/link {audience:restricted}

Re-copy a file/folder's active link (the same secret, nothing rotated). Managers only; Restricted returns the ordinary URL.

--json{ project, path, link, url, secret }

APIPOST /api/v1/resources/link/copy

Rotate a file/folder's link: the old one stops working for everyone who joined through it, a new one is minted with the same settings. Requires --yes; --dry-run lists who loses access.

--json{ project, path, link, url, replaced:true, losesAccess }

APIPOST /api/v1/resources/link/replace

Who can open one file or folder and why: your own effective role; for a project owner or workspace admin also the direct grants, inherited folder grants, pending invitations and the link state.

sharedoc access list clients/acme --project deals
sharedoc access list clients/acme/brief.md --json

--json{ project, path, kind, role, capabilities:{read,comment,write,manage}, sources, canManage, aclRevision, people?, inherited?, invitations?, link?, linkRecipients? }

APIGET /api/v1/resources/access

Give a person (an existing account) viewer, commenter or editor access to one file or folder. Adds to their membership access, never lowers it.

--json{ grant:{id,user,role,path,kind}, created, aclRevision }

APIPUT /api/v1/resources/grants

Take a direct grant away (by email or grant id). Reports the access they still have through a parent folder or membership. Requires --yes.

--json{ revoked, aclRevision, removed, stillHasAccessVia }

APIDELETE /api/v1/resources/grants/:id

Invite an email to one file or folder: an existing account is granted at once; anyone else gets a pending invitation (7 days) they redeem with that verified email. No email is sent unless --notify.

--json{ action:granted|invited, grant?|invitation?, emailSent, aclRevision }

APIPOST /api/v1/resources/invitations

Files and folders shared with you file-by-file (outside your project memberships), with role and URL.

--json{ items:[{project,projectName,workspace,path,kind,role,source,grantedAt,url}] }

APIGET /api/v1/shared-with-me

Files in a project (any project you can open — no connected folder needed).

sharedoc files list homa-legal
sharedoc files list homa-legal --depth 1 --json
sharedoc files list _inbox --since 1h --json
sharedoc files list sharedoc --status blocked --assignee me

--json{ project, path?, folders?:[{name,path,count}], files:[{path,name,kind,size,mime,version,updatedAt,thumbUrl,statuses,assignee:{id,name,email}|null,meta,invalid}] }

APIGET /api/v1/files?project=&status=&assignee=&unassigned=1

Print a file: markdown as text (latest revision), blobs as raw bytes. --thumb gives the small version of a picture or a video poster; --out writes to a file.

sharedoc files cat homa-legal contract-v3.md
sharedoc files cat homa-legal media/shot.png --thumb --out /tmp/shot.webp
sharedoc files cat _inbox 2026-09/ab12cd-scan.pdf > scan.pdf

APIGET /api/v1/files/content

Every image and link inside a markdown document, resolved to project paths — what to `files cat` next. Relative links are joined to the doc's folder; external URLs are listed as such.

sharedoc files links homa-legal notes/plan.md --json
sharedoc files links homa-legal notes/plan.md

--json{ project, path, links:[{src,text,image,project,path,kind:image|video|doc|file,exists,mime,size,thumbUrl}|{src,text,image,external:true,url}] }

APIGET /api/v1/files/links

Revisions of a markdown file.

--json{ revisions:[{version,size,contentHash,authorUserId,author:{id,name,email}|null,viaAgent,source,summary,createdAt}] }

APIGET /api/v1/files/history

Write a file. Markdown is 3-way merged into the live doc against --base, never overwritten.

sharedoc files put homa-legal contract-v3.md --from ./contract.md --base 7 --message "counsel edits"
cat plan.md | sharedoc files put homa-legal notes/plan.md --json
sharedoc files put homa-legal assets/site.png --from ./site.png

--json{ path, version, kind, merged, failedHunks, conflict }

APIPUT /api/v1/files/content?project=&path=&base=&source=cli&strict=&message=

Set a markdown doc's statuses — the `status` list in its YAML front-matter, edited in place (comments and other keys kept; the block is added when missing and removed when nothing is left). Keys you set or add must be in the project's statuses (`statuses list`); any key can be removed. Order: --set/--clear, then --remove, then --add. One revision, source `meta`.

sharedoc files status sharedoc issues/x.md --add ready-for-agent
sharedoc files status sharedoc issues/x.md --remove ready-for-agent --add in-progress --if-version 7 --json || echo "someone else claimed it"
sharedoc files status sharedoc issues/x.md --set done
sharedoc files status sharedoc issues/x.md --clear

--json{ project, path, version, changed, statuses, assignee:{id,name,email}|null, meta, invalid }

APIPOST /api/v1/files/meta (If-Match: <version>)

Set (or clear) a markdown doc's assignee — the `assignee` line in its front-matter: a person's email, or an agent's name (`assignee: Night shift`). `me` is you, or the agent whose token this is; `none` clears it. They must be able to open the project; they get a notification unless it is you. An agent's name is matched whatever its case, and only an agent is matched by name — a person is named by email.

sharedoc files assign sharedoc issues/x.md me
sharedoc files assign sharedoc issues/x.md [email protected]
sharedoc files assign sharedoc issues/x.md "Night shift"
sharedoc files assign sharedoc issues/x.md none

--json{ project, path, version, changed, statuses, assignee:{id,name,email}|null, meta, invalid }

APIPOST /api/v1/files/meta (If-Match: <version>)

Markdown docs across every project you can open in a workspace, found by their front-matter properties — the overnight runner's question ("what is ready for an agent?") in one call. Filters AND together; archived docs are left out unless asked. Newest change first; pages of 50 (--limit up to 500), `nextCursor` continues, --all follows every page. Someone who reaches a project only through a shared file sees just that file, and never who it is assigned to.

sharedoc docs list --status ready-for-agent --json
sharedoc docs list --assignee me --has-status
sharedoc docs list --status blocked --status in-progress --project sharedoc --project kid-learn
sharedoc docs list --status ready-for-agent --all --json | jq -c '.docs[]'

--json{ workspace, docs:[{id,project,path,name,statuses,assignee:{id,name,email}|null,meta,invalid,version,updatedAt,updatedBy:{id,name}|null,archived,openThreads}], nextCursor }

APIGET /api/v1/docs?workspace=&status=&assignee=&project=&unassigned=1&hasStatus=1&archived=0|1|all&sort=updated|path&limit=&cursor=

The same list with any filter tree: `{ and|or: [...] }` groups (4 deep, 50 conditions) of `{ field, op, value }`. Fields: status (contains, in, isEmpty, notEmpty), assignee (eq, in, isEmpty, notEmpty; 'me', an email or an id), project (eq, in), archived (eq, in), path (eq, in, startsWith), updatedAt (gt, lt; ISO, or 24h / 7d / 3m ago — m is months). A filter that never names archived matches live docs only; naming it anywhere (even in one or-branch) turns that off for the whole filter. Unsupported fields or ops are refused with the reason (exit 1).

sharedoc docs query --filter '{"and":[{"field":"status","op":"contains","value":"blocked"},{"field":"assignee","op":"eq","value":"me"}]}' --json
sharedoc docs query --filter '{"or":[{"field":"status","op":"isEmpty"},{"field":"assignee","op":"isEmpty"}]}' --sort project,path
sharedoc docs query --filter '{"field":"updatedAt","op":"gt","value":"7d"}' --fields path,statuses --all --json

--json{ workspace, docs:[…as docs list…], nextCursor }

APIPOST /api/v1/docs/query { workspace, filter?, sort?, fields?, limit? (≤ 500), cursor? }

Move or rename a file (its revisions, threads and comments follow it).

sharedoc files mv homa-legal draft.md contracts/v3.md
sharedoc files mv homa-legal scan.pdf scan.pdf --to-project homa-archive

--json{ project, path }

APIPOST /api/v1/files/move

Archive a doc — "closed", like an issue: off the tree and search, still readable at its URL with its comments and history; `files reopen` brings it back. Editing it from anywhere reopens it too. Requires --yes.

sharedoc files archive homa-legal old-draft.md --yes

--json{ ok: true, archived: true }

APIPOST /api/v1/files/archive

Reopen an archived doc in place (history, comments and URL intact).

sharedoc files reopen homa-legal old-draft.md

--json{ ok: true, archived: false }

APIPOST /api/v1/files/reopen

Alias of `files archive` (kept for scripts). Requires --yes.

sharedoc files rm homa-legal old-draft.md --yes

--json{ ok: true, archived: true }

APIPOST /api/v1/files/archive

Alias of `files reopen`.

sharedoc files restore homa-legal old-draft.md

--json{ ok: true, archived: false }

APIPOST /api/v1/files/reopen

Unified diff between two revisions (default: the previous one → the latest).

sharedoc files diff homa-legal contract-v3.md
sharedoc files diff homa-legal contract-v3.md --from 5 --to 7 --json

--json{ diff }

APIGET /api/v1/files/diff

A short-lived signed download URL for a blob (share it, curl it, feed it to a tool).

sharedoc files url _inbox 2026-09/ab12cd-scan.pdf --ttl 900 --json

--json{ url, expiresAt }

APIGET /api/v1/files/url

Threads and messages that reference a file ("discussed in n threads").

sharedoc files backlinks homa-legal contract-v3.md
sharedoc files backlinks homa-legal contract-v3.md --json

--json{ backlinks:[{threadId,messageId,project,doc,snippet,createdAt}] }

APIGET /api/v1/files/backlinks

Threads you can see: one doc with --doc, one project, or everything (open by default).

sharedoc threads list --doc homa-legal/contract-v3.md --json
sharedoc threads list --status all --mine

--json{ threads:[{id,projectSlug,anchorKind,docPath,anchor,status,title,createdBy:{id,name},lastMessageAt,messageCount,followerCount,rootSnippet,viaAgent}], nextCursor }

APIGET /api/v1/threads

One thread: anchor, status, followers, every message, and the references they carry.

sharedoc thread show 2b7df1a0-… --json
sharedoc thread show 2b7df1a0-…

--json{ thread, messages:[{id,author:{id,name},viaAgent,kind,bodyMd,editedAt,deletedAt,createdAt,reactions:[{emoji,userIds,others}]}], references, followers }

APIGET /api/v1/threads/:id

Start a doc-anchored thread (this is what a comment is). Quote the text you mean.

sharedoc thread create --doc homa-legal/contract-v3.md --quote "the parties agree" --body "Is this the signed wording? @Emily" --json
sharedoc thread create --doc homa-legal/contract-v3.md --lines 12-20 --body-file review.md

--json{ thread, message, references, unresolved }

APIPOST /api/v1/threads

Reply in an existing thread — prefer this over opening a new one.

sharedoc thread reply 2b7df1a0-… --body "Agreed — see [[homa-legal/appendix-b.md#L4-L9]]" --json
cat notes.md | sharedoc thread reply 2b7df1a0-…

--json{ message, references, unresolved }

APIPOST /api/v1/threads/:id/messages

Change which project one of your own channel posts or DMs says it is about (or `none` to clear it). Moves the label only — not the post.

sharedoc thread relabel 2b7df1a0-… sharedoc
sharedoc thread relabel 2b7df1a0-… none

--json{ thread }

APIPATCH /api/v1/threads/:id

Mark a thread resolved (only when you were asked to — resolving hides it).

sharedoc thread resolve 2b7df1a0-…

--json{ thread }

APIPATCH /api/v1/threads/:id

Reopen a resolved thread.

sharedoc thread reopen 2b7df1a0-…

--json{ thread }

APIPATCH /api/v1/threads/:id

Follow a thread (you are followed in automatically when you post or are mentioned).

sharedoc thread follow 2b7df1a0-…

--json{ thread }

APIPATCH /api/v1/threads/:id

Stop following a thread.

sharedoc thread unfollow 2b7df1a0-…

--json{ thread }

APIPATCH /api/v1/threads/:id

Rewrite one of your own messages (references are re-derived).

sharedoc thread edit 9c01a8b2-… --body "Fixed: @Emily-Ross owns this"

--json{ message, references, unresolved }

APIPATCH /api/v1/messages/:id

Tombstone one of your own messages. Requires --yes.

sharedoc thread delete 9c01a8b2-… --yes

--json{ ok: true }

APIDELETE /api/v1/messages/:id

Add (or with --remove, take back) an emoji reaction on a message.

sharedoc react 9c01a8b2-… 👍
sharedoc react 9c01a8b2-… 👍 --remove --json

--json{ reactions:[{emoji,userIds,others:[{key,name,avatar}]}] }

APIPOST /api/v1/messages/:id/reactions · DELETE …?emoji=

Channels and DMs you can see, with unread posts and mention counts.

sharedoc channels list
sharedoc channels list --json

--json{ conversations:[{id,kind,name,topic,isPrivate,projectSlug,memberCount,messageCount,lastMessageAt,me:{joined,notifyLevel,lastReadAt},unread,mentions,members?}] }

APIGET /api/v1/conversations

Audio huddles in the channels and DMs you can see, newest first: who started it, how long, who joined. Joining one needs a browser.

sharedoc huddles list
sharedoc huddles list --live --json

--json{ huddles:[{id,conversationId,conversation:{kind,name},threadId,messageId,startedBy:{id,name},startedAt,endedAt,durationSec,participants:[{userId,name}],live:[{userId,name,muted}],count}] }

APIGET /api/v1/huddles

Start a huddle in a channel or DM — posts the announcement and notifies as usual; joining the call needs a browser.

APIPOST /api/v1/conversations/:id/huddle

Create a channel (public by default). A project made with its channel toggle on already has #<slug>; --project gives one to a project that has none.

sharedoc channels create launch --topic 'Sept launch' --members [email protected]

--json{ conversation, created }

APIPOST /api/v1/conversations

Add workspace members to a channel you are in — the only way into a private one. A project's channel follows its project: use `members add --project` there.

sharedoc channels add plans [email protected] [email protected]

--json{ conversation, added, members:[{id,name,email,role,notifyLevel}] }

APIPOST /api/v1/conversations/:id/members

Join a public channel. You are in #general already, and in a project's channel when it has one — a project can be made without one, in which case its posts are labels on #general.

APIPOST /api/v1/conversations/:id/join

Leave a channel.

APIPOST /api/v1/conversations/:id/leave

Archive a channel (hidden for everyone; posts stay). Requires --yes.

APIPATCH /api/v1/conversations/:id

Delete a channel and every post in it — permanent, unlike archive. A project channel deleted this way stays gone. Requires --yes.

--json{ deleted:true, id, name }

APIDELETE /api/v1/conversations/:id

Invite another workspace into one of your channels, by the email of someone there (owners and admins of this workspace). They pick which of their workspaces joins and what it is called there; nobody gets a seat in yours. Open mode: everyone in it sees every post. --hub: each workspace sees your posts to everyone and its own threads, never another's. The mode is fixed once the first workspace joins. Not for DMs, project channels, #general, Slack-linked channels or the Talk channel.

sharedoc channel share acme --email [email protected]
sharedoc channel share support --email [email protected] --hub

--json{ invitation:{id,email,mode,expiresAt}, created, emailSent }

APIPOST /api/v1/conversations/:id/invitations

Invitations to shared channels sent to you, each with the workspaces you could connect it to. With a channel: as its host's owner or admin, who is invited and which workspaces are in it or waiting for their admin.

sharedoc channel invites
sharedoc channel invites acme --json

--json{ invitations:[{id,channel,host:{id,name},invitedBy,mode,expiresAt,workspaces:[{id,slug,name,role,direct,taken}]}] } · { mode, refusal, invitations:[{id,email,mode,expiresAt}], workspaces:[{id,name,status}] }

APIGET /api/v1/shared-channels/invitations · GET /api/v1/conversations/:id/invitations

Accept an invitation to a shared channel into one of your workspaces (--workspace; one you are a member of, not a guest in). It is private there unless --open. As an owner or admin there it connects at once; otherwise it waits for one of them (`channel approve`).

sharedoc channel accept 3f1c… --workspace cockpit --name brightmotion
sharedoc channel accept 3f1c… --workspace cockpit --open

--json{ status:"connected"|"pending", workspace, name, conversation }

APIPOST /api/v1/shared-channels/invitations/:id/accept

As an owner or admin of --workspace: let in a shared channel a member accepted (or --decline it). With no channel, list what is waiting.

sharedoc channel approve
sharedoc channel approve brightmotion --workspace cockpit

--json{ status, workspace, name?, conversation? }

APIGET /api/v1/shared-channels?workspace= · POST /api/v1/shared-channels/:id/approve|decline

End a shared channel for one workspace (owners and admins). Without --from: your workspace (--workspace) leaves a channel it joined. With --from: as the host, remove that workspace (its name or id, from `channel invites <channel>`). The side that goes loses the channel and its history, its own posts included; the host keeps everything, and a system post says who went. Requires --yes.

sharedoc channel disconnect brightmotion --workspace cockpit --yes
sharedoc channel disconnect acme --from Acme --yes

--json{ status:"left"|"removed", workspace }

APIPOST /api/v1/shared-channels/:id/leave · POST /api/v1/shared-channels/:id/remove

Read a channel or DM: posts newest-last with reply counts; every id is a thread id (`thread show` / `thread reply`).

sharedoc channel history general
sharedoc channel history general --project sharedoc
sharedoc channel history homa-legal --since 24h --json

--json{ conversation, threads:[{id,projectSlug,root:{id,authorName,viaAgent,bodyMd,createdAt,reactions},replyCount,lastReplyAt,participants}], nextCursor }

APIGET /api/v1/conversations/:id/messages

Post in a channel (the same as `thread create --channel`). Read the channel first.

sharedoc channel post general --body 'Deployed v0.10 — notes in [[ops/deploys.md]]' --project sharedoc --as-agent claude-code --as-model opus-5
sharedoc channel post general --body 'The whiteboard from today' --attach ./whiteboard.jpg

--json{ thread, message, references, unresolved, created }

APIPOST /api/v1/conversations/:id/messages

Message one or more people directly (opens the DM once, reuses it after), or `me` for a note to self. Without a body: just open it and print its id. An agent takes DMs only from whoever controls it unless they set `agents dms <agent> workspace`; anyone else is refused with a 403 naming who it takes them from.

sharedoc dm [email protected] --body 'Can you look at [[homa-legal/contract-v3.md]] today?'
sharedoc dm me --body 'the staging token is in 1Password'
sharedoc dm emily --json

--json{ conversation, thread, message, references, unresolved, created }

APIPOST /api/v1/conversations {kind:dm} → POST /api/v1/conversations/:id/messages

Your drafts, the variant sets waiting for you to choose, scheduled and failed messages. Private: nobody else sees any of it.

sharedoc drafts list
sharedoc drafts list --sets --json
sharedoc drafts list --resolved

--json{ drafts:[{id,status,conversationId,threadId,bodyMd,viaAgent,variantId,sendAt,error,target:{kind,name,members,threadSnippet}}], sets:[{id,status,note,viaAgent,proposedSendAt,chosenLabel,chosenEdited,messageId,variants:[{id,label,bodyMd}],target}] }

APIGET /api/v1/drafts?workspace=&status=

Draft a message for your human instead of posting it: one body goes into their composer (unless it has text in it), several become a set of versions they choose from. Nothing is sent.

sharedoc draft create sharedoc --thread 2b7df1a0-… --variants-file - --note "Colin asked when the deploy lands; B commits to a date" < replies.json
sharedoc draft create general --body 'Deployed v0.30 — notes in [[ops/deploys.md]]'
sharedoc draft create @colin --body 'Can we move standup?' --at 'mon 9:00'

--json{ draft, created } | { set, variants, busy, created } (--wait adds outcome)

APIPOST /api/v1/drafts

One draft, scheduled message or variant (a set id works too).

--json{ draft, set }

APIGET /api/v1/drafts/:id

Change a draft's text or a variant's label, schedule, reschedule or unschedule it.

sharedoc draft edit 9c01a8b2-… --in 2h
sharedoc draft edit 9c01a8b2-… --unschedule

--json{ draft, set }

APIPATCH /api/v1/drafts/:id

Send a draft or scheduled message now, as a post by you. For a person at a terminal — agents: never send for the human.

--json{ thread, message, references, unresolved, created, draftId }

APIPOST /api/v1/drafts/:id/send

Throw a draft away. Requires --yes.

--json{ ok, deleted, set }

APIDELETE /api/v1/drafts/:id

A variant set: its versions, and — once the human has chosen — which one won and whether they edited it. --wait blocks until they decide.

sharedoc draft set show 51c0…
sharedoc draft set show 51c0… --wait 30m --json

--json{ set:{id,status,note,chosenVariantId,chosenLabel,chosenEdited,messageId,resolvedAt,variants}, variants }

APIGET /api/v1/draft-sets/:id?wait=

Close a variant set without sending anything. Requires --yes.

--json{ set }

APIPOST /api/v1/draft-sets/:id/dismiss

Add a version to an open set (six at most). The human sees it appear.

--json{ variant, set }

APIPOST /api/v1/draft-sets/:id/variants

Take a version out of its set (a set left empty is dismissed). Requires --yes.

--json{ ok, deleted, set }

APIDELETE /api/v1/drafts/:id

A person's choice from a terminal: put a version in the composer (the default), --send it, or schedule it with --at / --in. Agents: never pick for the human.

--json{ draft, set } | { thread, message, … }

APIPOST /api/v1/drafts/:id/use · POST …/send · PATCH …{sendAt}

Connect a Slack workspace to your account: opens Settings → Slack's Add to Slack in your browser (it must be signed in to share-doc as you) and waits until Slack hands over access. Choose which conversations come in on that page. Running it again for a connected workspace reconnects it and keeps its links.

sharedoc slack connect
sharedoc slack connect --workspace brightmotion

--json{ connection:{id,team:{id,name,icon},slackUser:{id,handle,avatar},scopes,status,links,…}, created }

APIGET /api/v1/slack/connections (then the browser: /settings/slack/connect → Slack → /api/v1/slack/oauth/callback)

Your Slack connections: the Slack workspace, your Slack handle, how many conversations are linked, status (ok; revoked: reconnect; disconnected), when the last event arrived. Never a token.

sharedoc slack list
sharedoc slack list --json

--json{ connections:[{id,workspaceId,team:{id,name,icon},slackUser:{id,handle,avatar},scopes,status,readSync,autoLinkDms,lastEventAt,lastPostAt,lastError,links,createdAt,updatedAt}] }

APIGET /api/v1/slack/connections

The Slack conversations a connection brings in: name, read only or two-way, health, how far their history has come in, the Slack id and the share-doc conversation id. With --set <conversation> --direction: `both` makes it two-way (what you post goes to Slack as you), `in` read only, `off` removes the link (its conversation here is archived with its history; nothing changes in Slack). A conversation not linked yet is found in Slack by id or name and linked with --backfill days of history. Everything not named stays as it is.

sharedoc slack links
sharedoc slack links Brightmotion --json
sharedoc slack links --set "#design" --direction in
sharedoc slack links --set C0123ABCD --direction both --backfill 7

--json{ connection, team, links:[{id,channel,kind,name,conversationId,direction:in|both,addedBy,status,slackReadTs,lastTs,backfill:{from,until,doneAt},lastError,createdAt,archivedAt}] } | with --set: { changes:[{channel,name,change:added|restored|removed|direction|failed,…}], links }

APIGET /api/v1/slack/connections/:id [?all=1]; with --set: GET …/conversations, PUT /api/v1/slack/connections/:id/links {set:{<channel>:in|both|off}, backfillDays}

How your Slack connections are doing: per connection its status, last event, last post, last error and switches; per linked conversation read only or two-way, health, how far its history has come in, its newest message and your Slack read cursor.

sharedoc slack status
sharedoc slack status Brightmotion --json

--json{ connections:[{ connection:{…}, links:[{…as slack links}] }] }

APIGET /api/v1/slack/connections, then GET /api/v1/slack/connections/:id per connection

The files on a message that came from Slack (they stay in Slack; the hub fetches them for you, with the same access as the message). Without --index: list them, numbered from 1, with a `gone` flag for one Slack no longer serves. With --index n: download file n to --out, or to its own name in the working directory (refused if that exists, unless --force). Message ids and their slackFiles are on `thread show --json`.

sharedoc slack file 5f0c…
sharedoc slack file 5f0c… --json
sharedoc slack file 5f0c… --index 1 --out /tmp/shot.png

--json{ files:[{id,name,mime,size,width,height,kind:image|video|pdf|file,url,thumbUrl,permalink,gone}] } | with --index: { path, bytes, name, mime }

APIGET /api/v1/slack/files?message=<id>, then GET /api/v1/slack/files/:id

People in a connected Slack workspace you can start a DM with (from share-doc's copy of its member list; bots and deactivated accounts left out). Matches the name, @handle or email; share-doc teammates are marked and listed first. Use a handle or the Slack id with `slack dm`.

sharedoc slack people colin
sharedoc slack people --team Brightmotion --json

--json{ connection, team, people:[{id,name,handle,avatar,teammate:{id,name}|null}] }

APIGET /api/v1/slack/connections/:id/people?q=

Start a Slack DM (one person) or group DM (two to eight) from share-doc, as you, and bring it in as a private share-doc conversation; one that is already linked just opens, one you removed comes back with its history. Nothing is sent to Slack until you post in it (`channel post <conversation-id>`).

sharedoc slack dm @colin
sharedoc slack dm @colin @dana --json

--json{ change:existing|restored|added, conversationId, workspace, name, link }

APIPOST /api/v1/slack/connections/:id/dm {users}

Disconnect a Slack workspace: Slack revokes the token and share-doc deletes it, and the conversations it brought in are archived with their history (their composers close). Connecting the same Slack account again lets you tick them back in. Nothing changes in Slack. Requires --yes; --dry-run lists what would be archived. --forget then removes a disconnected connection from your list (its archived conversations stay).

sharedoc slack disconnect Brightmotion --dry-run
sharedoc slack disconnect Brightmotion --yes

--json{ connection, archived:[link], slackRevoked, slackError } | { forgotten }

APIDELETE /api/v1/slack/connections/:id [?forget=1]

Full-text search over messages, doc comments and file contents, fuzzy over paths, folders, channels and people — everything you can open, shared folders included. `in:<project>` covers its docs, its channel, and any post labelled with it. Filters ride in the query: in:#channel|project|dm, from:me|email|name|agent, is:unread, is:archived (archived docs only; excluded otherwise), has:file, before:/after:2026-09-01|7d, and for files only status:<key> (repeat = any of them), assignee:me|email|name, is:unassigned, has:status (a search for other things with these says so in query.notes rather than widening). `--types` picks any combination (files,folders,messages,channels,people) and, with no query words, browses what is recent in scope; `--workspace all` searches every workspace you can see; `--cursor` continues one group.

sharedoc search 'contract deadline' --json
sharedoc search 'status:blocked assignee:me' --types files
sharedoc search 'deploy' --in '#general' --after 7d
sharedoc search 'invoice' --scope files
sharedoc search 'is:unread from:emily' --scope messages
sharedoc search 'sync' --types files,folders --workspace all
sharedoc search 'budget' --types messages --source comments --project sharedoc
sharedoc search --types files --project sharedoc --folder specs --limit 20

--json{ query:{text,filters,unresolved[],conflicts[],fullText,notes[]}, scope, types[], filters:{messageSource,presentation,project,folder,conversation}, groups:{files[],folders[],messages[],threads[],channels[],people[]}, counts (shown, not totals), page:{<group>:{shown,hasMore,cursor}}, coverage:{mode,workspaces[]}, results[] }

APIGET /api/v1/search

The change log (who did what, when) from a cursor; --follow streams.

--json{ events:[{id,kind,workspace,project,actor,viaAgent,subject,payload,createdAt}], nextCursor }

APIGET /api/v1/events

Your notifications (mentions, DMs, replies in threads you follow, new threads on docs you follow). Unread only by default.

sharedoc unread
sharedoc unread --watch --json

--json{ notifications:[{id,kind,title,snippet,threadId,conversationId,conversationName,projectSlug,docPath,actor,viaAgent,readAt,createdAt}], unread, mentions, nextCursor }

APIGET /api/v1/notifications

Mark notifications read by id.

--json{ read:n }

APIPOST /api/v1/notifications/read

Mark everything read (needs --yes), or everything in one conversation / before a time.

--json{ read:n }

APIPOST /api/v1/notifications/read

Show or change your notification preferences (spec §3.8): level, thread replies, doc follows, email timing, snooze, working hours.

sharedoc notify prefs
sharedoc notify prefs --set level=all,emailMode=never
sharedoc notify prefs --set snoozeUntil=2026-09-04T17:00:00Z
sharedoc notify prefs --set hoursDays=weekdays,hoursStart=540,hoursEnd=1080

--json{ prefs:{email,browser,pushAlways,level,threadReplies,docFollows,inboxDrops,invites,emailMode,awayMinutes,digestHour,markRead,snoozeUntil,hoursDays,hoursStart,hoursEnd,timezone} }

APIGET|PUT /api/v1/notify/prefs

Two-way sync a local directory with a project (long-running by default).

sharedoc connect homa-legal ~/deals/homa
sharedoc connect homa-legal ./homa --once --json
sharedoc connect homa-legal ./homa --once --strict   # exit 4 on a conflict
sharedoc connect homa-legal ./homa --reset

--json{ pulled, pushed, merged, conflicts } (--once only)

APIPOST /api/v1/connections (register) · GET …/policy · PUT /api/v1/files/content (push) · Hocuspocus + GET /api/v1/files (pull)

Add a folder ⇄ project pair, or channels to mirror, to this machine's sync set (~/.config/share-doc/sync.json).

sharedoc sync add homa-legal ~/deals/homa
sharedoc sync add ops ~/ops --strict
sharedoc sync add --channel general,homa-legal
sharedoc sync add --channels --dms --dir ~/chat
sharedoc sync add --channels --workspace brightmotion   # a login with no workspace on it

--json{ pair:{project,dir,strict,workspace?}, path, firstPush?:{files,bytes,ignored} } | { channels:{dir,include,exclude,dms,history,workspace?}, path }

Remove a folder pair (<dir>), one channel (#name) or the whole channel mirror (channels) from the set, and disconnect the pair's connection on the hub. Never touches files — local or on the server: the way out for a paired folder that went `missing` when you meant to stop syncing it.

sharedoc sync rm ~/deals/homa
sharedoc sync rm #random
sharedoc sync rm channels

--json{ removed, path }

A paired folder is gone (`missing` in `sync status`) and you did mean to delete everything in it: archive on the server every file its connection syncs, as one batch (`sync undo` reopens it), then unpair it as `sync rm` does. The running sync never reads a vanished folder as deletes. Requires --yes; refuses a folder that is still there.

sharedoc sync archive-missing ~/old-notes --dry-run
sharedoc sync archive-missing ~/old-notes --yes

--json{ project, dir, batch, archived:[path], failed:[{path,error}], disconnect } | { dryRun:true, project, dir, archive:[path] }

The sync set as configured: pairs, channel rules, resolved paths.

--json{ projects:[{project,dir,strict}], channels:{dir,include,exclude,dms,history}|null, path }

The set as it is right now: per pair state/files/last push/pull/error, the channel mirror, whether `sync run` is up (and the service manager's view: launchd on macOS, systemd on Linux).

--json{ running:{pid,mode,since}|null, service:{manager,installed,loaded,running,pid}|null, pairs:[{project,dir,state,files,lastPushAt,lastPullAt,lastError,counts,held,heldDeletes:{batch,since,count,paths}|null,approve}], channels:{dir,state,conversations,threads,lastEventAt,lastError}|null } (state `missing`: the folder is gone — nothing syncs or is archived until it is back)

THE process: every pair and the channel mirror, live, until Ctrl-C (one lock per machine). --once reconciles everything and exits.

sharedoc sync run
sharedoc sync run --once --json

--json{ pairs:[{project,dir,pulled,pushed,merged,conflicts,error}], channels:{dir,conversations,threads,error}|null } (--once only)

Run `sync run` as a user service — launchd on macOS, systemd --user on Linux — that starts at login and is restarted if it dies. Idempotent. Waits (up to 20 s) for every pair and the channel mirror to report live or an error before printing; `settled: false` means check `sync status` in a moment.

sharedoc sync install
sharedoc sync status

--json{ unit, program:{argv,via}, service:{manager,installed,loaded,running,pid}, log, journal, linger, settled, pairs:[{project,dir,state,lastError}], channels:{dir,state,conversations,lastError}|null, gated:[dir] }

Stop and remove the user service (launchd / systemd). The set and every folder stay.

--json{ removed, unit }

Tail the service log: ~/Library/Logs/sharedoc/sync.log on macOS, the journal (journalctl --user -u sharedoc-sync) on Linux.

sharedoc sync logs
sharedoc sync logs --follow

The hub's inventory of machine connections ("connections" in Settings): status, last seen vs last synced, whether settings are applied. Owners see their local paths; project managers a coarse row per machine. `sync list` is this machine's local set.

sharedoc sync endpoints --project homa-legal
sharedoc sync endpoints --all --json

--json{ project?, canManage?, syncRevision?, connections:[{id,project,device,owner,own,root,mode,defaultMode,state,status,live,lastSeenAt,lastSuccessAt,configRevision,appliedRevision,applied,dir?,host?,lastError?,rules?,thisMachine}] }

APIGET /api/v1/connections?project=

Pause a connection: transfers stop, folder rules are kept, local edits wait. The running sync notices within 30 s.

--json{ connection, before }

APIPATCH /api/v1/connections/:id {state:paused}

Approve what a connection is waiting on. --deletes: the files its folder deleted in bulk (more than 25 at once), held rather than archived on the server — this archives them. Otherwise, in a workspace with large files turned off (workspace settings → Storage; on, the default, nothing waits): its big first push (a `sync add` past 50 files or 20 MB without --yes), or with --file / --held the big files it holds over the workspace's ask-first size. Only on the person's say-so — `sync status` and the log say what is waiting.

--json{ connection, before, approved } | --deletes: { connection, before, decision, heldDeletes:{batch,since,count,paths} }

APIPOST /api/v1/connections/:id/approve

Keep the files a connection's folder deleted in bulk and is holding: nothing is archived, and the folder pulls them back from the server. (Putting the files back does the same.)

--json{ connection, before, decision, heldDeletes }

APIPOST /api/v1/connections/:id/discard

Reopen every file one burst of a folder's deletes archived on the server, in one call — by default the newest burst with anything still archived (last 30 days). --list shows the bursts. The folder, if still paired, pulls them back.

sharedoc sync undo 3f2a9c1e
sharedoc sync undo ~/kid-learn/docs --list

--json{ batch, reopened:[path], skipped:[{path,reason}] } | --list: { connection, batches:[{batch,count,stillArchived,firstAt,lastAt}] }

APIPOST /api/v1/connections/:id/undo · GET /api/v1/connections/:id/archives

Resume a paused connection: it re-reads its settings and reconciles.

--json{ connection, before }

APIPATCH /api/v1/connections/:id {state:active}

Disconnect a connection on the hub: its credential is revoked and any running sync stops; local files, cloud files and membership stay. Requires --yes. Reconnecting is a new `sync add` / `connect`.

--json{ connection, before } | { dryRun:true, before, after, keeps }

APIPOST /api/v1/connections/:id/disconnect

What one connection syncs, folder by folder: list the tree with each folder's rule, effective state and why; `set <path> --mode on|off|inherit` changes a rule (a narrower On beats an ancestor Off); `--default` sets the connection default; `--clear-children <path>` removes overrides under a folder.

sharedoc sync folders 1a2b3c4d
sharedoc sync folders 1a2b3c4d set media --mode off
sharedoc sync folders 1a2b3c4d set media/previews --mode on
sharedoc sync folders 1a2b3c4d --default off --dry-run

--json{ connection, policy, rules, folders:[{path,rule,projectDefault,effective:{selected,source,at},mixed,counts}], impact:{selected,selectedBytes,excluded,excludedBytes,total,totalBytes} }

APIGET | PUT /api/v1/connections/:id/folder-rules · PATCH /api/v1/connections/:id

A project's folder sync defaults (what connections that use folder defaults do with each folder, future folders included). Without --sync-default: list. The root is on|off; other folders may inherit.

sharedoc folders settings --project homa-legal
sharedoc folders settings media --project homa-legal --sync-default off

--json{ project, canManage, syncRevision, defaults:{path:mode}, folders:[…], impact }

APIGET | PUT /api/v1/projects/:slug/sync-defaults

Your devices (one per ShareDoc installation) with their connections, grouped by machine.

--json{ devices:[{id,label,platform,clientVersion,lastSeenAt,connections:[…]}], unmanaged:[…] }

APIGET /api/v1/devices

Rename a device's label; its identity and connections are unchanged.

--json{ device:{id,label} }

APIPATCH /api/v1/devices/:id

Disconnect every connection a device holds for you (never erases its disk). Requires --yes; --dry-run lists the affected projects first.

--json{ device, disconnected:[{id,project,dir}], count }

APIPOST /api/v1/devices/:id/disconnect

This help. --json dumps the full command table for agents.

The live data contract: entities, fields, enums, and the command table.

APIGET /api/v1/schema

Print the CLI version.

Turn usage reporting on or off, or show whether it is on. After each command the CLI tells the server it is logged in to the command's name, the names of the flags given (never their values or any arguments), the exit code, the duration, the CLI version, OS and architecture. Nothing about files, paths, projects or messages. Also off with SHAREDOC_TELEMETRY=0 or DO_NOT_TRACK=1.

sharedoc telemetry
sharedoc telemetry off
SHAREDOC_TELEMETRY=0 sharedoc files list acme

--json{ enabled, decidedBy, file? }

Update this CLI in place: runs the installer from the server it targets, then restarts the sync service.

sharedoc update
sharedoc update --dry-run

--json{ server, installer, bundle, running?, changed, before:{path,exists,size,sha256}, after:{…}, service:{manager,installed,loaded,running,pid,restarted,error}|null }