CLI Guide

Upload and manage pages from your terminal. Works for both humans and AI agents.

Installation

Install globally via npm:

npm install -g @sharedrop/cli

Or run without installing using npx:

npx @sharedrop/cli upload report.html

Authentication

The CLI resolves credentials in this order (first match wins):

  1. --token flag: Highest priority. Overrides everything for a single command.
  2. SHAREDROP_TOKEN environment variable: Best for CI/CD.
  3. .env file in the current directory: Project-level config.
  4. Stored credentials from sharedrop login: Interactive browser-based auth.

By default the CLI targets https://sharedrop.cloud. Point it at another instance with the --url flag or the SHAREDROP_URL environment variable (same precedence: flag over env over .env).

Interactive Login

sharedrop login

Opens your browser to authenticate with sharedrop, using the same one-command flow as gh or glab. A CLI-specific key is created and stored in your OS config directory, so every later command just works from any directory. No copy-paste, no env var.

Stored credential location by platform:

OSPath
macOS~/Library/Preferences/sharedrop-nodejs/config.json
Linux~/.config/sharedrop-nodejs/config.json
Windows%APPDATA%\sharedrop-nodejs\Config\config.json

CI/CD Setup

Set SHAREDROP_TOKEN in your CI environment:

export SHAREDROP_TOKEN=sd_your_api_key_here
sharedrop upload report.html --json

Output Modes

The CLI auto-detects your terminal:

  • TTY (interactive terminal): Human-friendly output with tables, colors, and spinners
  • Non-TTY (piped/CI): JSON output, no colors, no spinners

Force JSON output in any context with the --json flag:

sharedrop list --json

JSON output follows the same structure as the REST API: { "data": ... } for success, { "error": { "code": "...", "message": "..." } } for errors.

When an upload changes or blocks content, human output prints the warning messages to stderr. JSON output keeps stdout machine-readable: data.warnings is always present on upload and update (an empty array for a clean upload), and each warning has a code to branch on. See Upload JSON.

Exit Codes

CodeMeaning
0Success
1General error
2Authentication required (no token found locally)
3Authentication failed: the server rejected the token (invalid, revoked or expired, a 401) or refused the action (a 403)
4Rate limited (429 from API)
5Not found (404 from API)
6Validation error (bad input)
7Payment required (402 from API)

Exit 1 also covers two cases worth knowing:

  • TOKEN_EXPIRED: the short-lived upload token for this one upload expired before it finished. Your API token is fine; run the same command again.
  • sharedrop check found something the upload would change or block (see sharedrop check).

Exit code 7: the account is read only

A failed subscription payment that is still unpaid after 21 days puts the account into read only. Any command that writes then fails like this:

$ sharedrop upload report.html
Error: Your account is read only because a payment failed. Update your card at sharedrop.cloud/dashboard/settings/billing to start uploading again.
$ echo $?
7

The message is printed in red on stderr and nothing is uploaded. With --json you get the same thing machine readable, with no pricing block:

{
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Your account is read only because a payment failed. Update your card at sharedrop.cloud/dashboard/settings/billing to start uploading again."
  }
}

This takes the CLI's plain error path, the same one every non-billing error takes, so a request_id field may also appear in the JSON, with a matching Request ID: line in the human output. Quote it if you contact support. Today's 402 body carries no request id, so in practice you see just the message, but do not write a parser that assumes the object has exactly two keys.

Update the card at the address in the message. The lock lifts on its own at the next successful payment, and the same command works again with nothing else to do.

Reading keeps working: list, get, whoami and delete work while the account is locked, and so do fetch and download for documents. The lock drops the plan to Free, so 14 days later fetch and download fail with not found for images, video and archives until the plan is restored. See Failed payments for the full timeline.

Commands

sharedrop upload

Upload a file to create a new page. Accepts HTML, PDF, MHTML, Markdown, JSON, JSONL, source code, plain text, Word documents, spreadsheets, images, and video (or a folder for an HTML bundle). Documents upload on every tier; images and video require Pro. The bytes stream directly to storage, never base64.

If an HTML upload contains tags or attributes that Sharedrop removes for safety, the command reports each removal after the upload succeeds. To see this before publishing, run sharedrop check first.

Size limits: each file can be up to your plan's per-file limit (Free 10 MB, Pro and Team 100 MB). HTML and other text files (Markdown, source code, plain text, JSON, JSONL, MHTML, skills, Word documents, spreadsheets) and SVG images are capped at 10 MB on every plan. A folder bundle is capped at the plan's per-file limit across all its files together. An oversized upload fails with FILE_SIZE_EXCEEDED before any bytes are sent. For larger content, split it, or upload it as a zip with sharedrop archive: it is stored as a download-only archive (Pro plan or higher).

sharedrop upload <file> [options]

Arguments:

ArgumentDescription
filePath to a file (HTML, PDF, Markdown, JSON, image, and more), a folder for an HTML bundle, or - to read from stdin

Options:

FlagDescription
--title <string>Page title. Default: a new single file takes its file name without the extension (report.html becomes report); stdin (-) and folders take the HTML <title> (for a folder, the entry file's); --page-id keeps the page's current title
--visibility <string>public, private, or shared (default: private)
--mode <string>static or interactive, HTML only. Default: a new page takes your account's default upload mode (interactive unless you changed it in settings); a re-upload with --page-id keeps the page's current mode
--entry <file>Entry HTML for a folder/bundle upload, relative to the folder (default: index.html)
--workspace <id|address>Upload to a workspace, by its id or address (see sharedrop workspaces)
--personalUse your personal space even when a default workspace is set
--folder <id|path>File the new page into a folder, for single files and folder bundles. Accepts a folder id or a slash path like reports/q3, auto-creating missing segments. A workspace upload uses that workspace's folders (Team plan); a personal upload uses your own (Pro plan or higher). Ignored on re-upload
--page-id <id>Re-upload over an existing page: keeps the same URL and records a new version
--to <slug|id>Claim a reserved address created with sharedrop reserve. Single file only; mutually exclusive with --page-id, --folder, and folder bundles. See sharedrop reserve
--jsonForce JSON output

Workspaces are part of the Team plan and are created in the dashboard. Anyone invited to one can upload to it with --workspace, whatever their own plan. Run sharedrop workspaces to see yours and their addresses, then pass the address, for example --workspace ascend. See Workspaces and seats. To stop repeating it, set a default workspace.

Examples:

Upload a file:

sharedrop upload report.html --title "Q1 Report" --visibility public

Upload from stdin (for agents piping HTML):

cat report.html | sharedrop upload - --title "Generated Report"

Generate and upload in one pipeline:

echo "<h1>Hello from CI</h1>" | sharedrop upload - --title "CI Build Output" --json

Upload an HTML slide deck:

# deck.html contains <meta name="sharedrop:kind" content="slides" />
sharedrop upload deck.html --title "Q3 review" --visibility public

There is no --slides flag and none is needed. An HTML file carrying the in-file marker uploads as a deck, gains a fullscreen Present mode, and can be opened on a TV by adding ?present=1 to its URL. See the slide decks guide.

Upload JSON

With --json (or when piped), upload and update <id> <file|folder> print:

{
  "data": {
    "id": "3f0c2b4e-8f7a-4c1d-9e2b-1a2b3c4d5e6f",
    "title": "Q3 report",
    "url": "/scottoau/ab12cd34ef",
    "full_url": "https://sharedrop.cloud/scottoau/ab12cd34ef",
    "kind": "html",
    "mode": "interactive",
    "visibility": "private",
    "was_reupload": false,
    "version": 1,
    "scripts_will_run": false,
    "external_resource_hosts": ["cdn.jsdelivr.net"],
    "warnings": [
      { "code": "images_extracted", "detail": "img", "count": 2, "message": "2 inline images were moved to hosted storage." },
      { "code": "external_refs_block_scripts", "detail": "cdn.jsdelivr.net", "count": 1, "message": "Scripts will not run because the page loads resources from 1 external host. Turn on external network for this page or vendor the files." }
    ],
    "same_title_pages": [
      { "id": "7d1e0a9c-2b3f-4e5d-8c7b-6a5f4e3d2c1b", "full_url": "https://sharedrop.cloud/scottoau/zz98yy76xx", "updated_at": "2026-10-06T22:14:03.000Z" }
    ]
  }
}
FieldMeaning
modeThe mode the page actually got, after the account default or the page's existing mode was applied
was_reuploadtrue when this replaced an existing page (--page-id or update)
versionThe page's version number. It starts at 1 and goes up by one on every re-upload, so a revision that updated in place shows the same id and url with a higher version
scripts_will_runWhether the page's scripts run right now: interactive mode, an HTML or slides page, scripts not blocked, and either external network on or no external hosts. Changing the page's settings later can change it
external_resource_hostsHosts the stored HTML loads resources from. With external network off, these stop an interactive page's scripts
warningsAlways present (possibly empty). Codes: removed_tag, removed_attribute, images_extracted (count inline images moved to hosted storage) and external_refs_block_scripts (detail lists the hosts)
same_title_pagesOnly on a new page: up to 5 of your existing pages with exactly the same title (ignoring case), newest first. A hint, not an error: use --page-id if you meant to revise one
skippedFolder bundles only, always present: files left out, each with path and reason (hidden file or unsupported file type)

Human output prints the title, URL, ID, the effective mode and the version, with any warnings on stderr.

Uploading a large file (over 30 MB) or storing something download-only (a database dump, a build tarball, a big .zip)? Use sharedrop archive instead. upload is for files Sharedrop renders; archive is for bytes you want to store and hand back.


sharedrop check

Run the real upload checks on a file or folder without publishing. check streams the bytes to quarantine exactly like upload, runs the server's sanitiser, image extraction, slides detection, size limit and external-host check, then deletes the copy. No page is created or changed, and no page slot is used.

Because check signs like an upload, it needs a free page slot and storage headroom for the file (a check with --page-id needs no free slot). At your page or storage cap it fails with the same limit error upload would give, and exits 7. It still never uses a page slot or publishes anything.

sharedrop check <file|folder> [options]
FlagDescription
--mode <string>Check as static or interactive (default: the mode upload would use)
--page-id <id>Check as a re-upload of this page (its mode applies unless --mode is set)
--slidesCheck a single HTML file as a slide deck
--entry <file>Entry HTML for a folder (default: index.html)
--workspace <id|address>Check as an upload to this workspace, by id or address (the same option as upload --workspace)
--personalUse your personal space even when a default workspace is set
--jsonForce JSON output

Exit code: 1 when the upload would change or block something (would_change is true), 0 when it would publish as-is. Other errors use the normal exit codes.

would_change is true when the file is too large, or when any warning is removed_tag, removed_attribute or external_refs_block_scripts. Moving inline images to hosted storage (images_extracted) alone does not count as a change.

JSON output:

{
  "data": {
    "kind": "html",
    "mode_effective": "interactive",
    "detected_slides": false,
    "size_ok": true,
    "size_bytes": 48211,
    "size_limit_bytes": 26214400,
    "title": "Q3 report",
    "warnings": [ { "code": "removed_tag", "detail": "iframe", "count": 1, "message": "Removed 1 <iframe> element." } ],
    "images_extracted": 2,
    "external_resource_hosts": [],
    "scripts_would_run": true,
    "same_title_pages": [],
    "would_change": true
  }
}

A folder adds "files" (the number of files in the bundle). If the size is refused before the checks can run, data is { "size_ok": false, "size_bytes", "size_limit_bytes" (or null), "would_change": true, "warnings": [], "message" } and the exit code is 1.

sharedrop check report.html --json && sharedrop upload report.html --json

sharedrop archive

Upload a large file as a download-only archive (Pro plan or higher). The bytes stream straight to storage, files over 30 MB upload in resumable parts, and the archive is always private. Full walkthrough in the Archives guide.

sharedrop archive <file> [options]

Options:

FlagDescription
--title <string>Page title (default: derived from the file name)
--folder <id|path>File the archive into a folder (id or slash path; missing segments are created), in the workspace when one applies
--workspace <id|address>Upload to a workspace, by id or address
--personalUse your personal space even when a default workspace is set
--store-as-fileStore any file as a download-only archive, bypassing the archive-extension check (for a large non-archive file)
--jsonForce JSON output

Examples:

sharedrop archive backup.sql.gz --title "Nightly DB backup"
sharedrop archive huge-export.csv --store-as-file   # any file, stored download-only

Download it back with the archive-aware sharedrop download <id>. Use sharedrop delete <id> to move it to charged trash for 7 days. Run sharedrop trash empty only when you intend permanent deletion. Archives cannot be re-uploaded over: delete and upload a new one to replace.


sharedrop list

List your pages. The table includes each page's ID. Copy it into get, update, delete, or share.

sharedrop list [options]

Options:

FlagDescription
--limit <number>Results per page (default: 50, max 100)
--cursor <string>Pagination cursor
--workspace <id|address>List a workspace's pages, by id or address
--personalUse your personal space even when a default workspace is set
--folder <id|path>List the pages inside a folder (id or existing slash path), in the workspace when one applies
--jsonForce JSON output

Example:

sharedrop list --limit 10
sharedrop list --folder reports/q3   # pages filed under a folder

Find pages with a single query matched across title, slug, id, and file type at once, so jpeg finds your image uploads and report finds them by name. Scoped to your own pages.

sharedrop search <query> [options]

Options:

FlagDescription
--limit <number>Results per page (default: 50, max 100)
--cursor <string>Pagination cursor
--workspace <id|address>Search a workspace's pages, by id or address
--personalUse your personal space even when a default workspace is set
--jsonForce JSON output

Examples:

sharedrop search jpeg            # every JPEG you've uploaded
sharedrop search "q3 report"     # match by title
sharedrop search ubbsrh8rwx      # match by slug or id

sharedrop get

Get details for a specific page.

sharedrop get <ref> [options]

<ref> can be the page id, its slug, or a full page URL, whichever is easiest to paste. The same applies to update, delete, and share.

Options:

FlagDescription
--jsonForce JSON output

Example:

sharedrop get 550e8400-e29b-41d4-a716-446655440000
sharedrop get ubbsrh8rwx
sharedrop get https://sharedrop.cloud/you/ubbsrh8rwx

sharedrop fetch

Pull a page's raw content: the original file bytes, not the sandboxed viewer page. Built for an agent reading a page (its own, a public one, or one shared to it) into its context. get returns metadata; fetch returns the content itself. Available on every tier.

sharedrop fetch <id> [options]

By default the raw bytes stream to stdout (no log line), so you can pipe them straight into another tool. Use --output to write a file.

Options:

FlagDescription
-o, --output <path>Write the bytes to a file (- for stdout, the default)
--jsonForce JSON output

Examples:

sharedrop fetch ubbsrh8rwx                 # raw content to stdout
sharedrop fetch ubbsrh8rwx -o report.html  # write to a file
sharedrop fetch ubbsrh8rwx | grep -i title # pipe into another tool

Distinct from download (which writes a zip of the full artefact for a human). fetch returns the raw root document with its real content type and is the agent-native read path.

Archives can't be fetched: sharedrop fetch on an archive fails with ARCHIVE_DOWNLOAD_REQUIRED, and JSON output includes error.download_url. Use sharedrop download <id> for archives. An unknown id or slug fails with a not-found error (exit code 5).

An image or video page that is still in its safety check can only be fetched or downloaded by its owner. An image, video or archive page whose paying plan lapsed more than 14 days ago cannot be fetched or downloaded by anyone until the plan is restored. Both fail with the same not-found error.


sharedrop download

Download a page's complete artefact as a zip: the root document plus every asset (images, CSS, JS) beneath it, with their original relative paths preserved. Use download when you want the whole bundle on disk; use fetch when you only need the raw root document.

sharedrop download <id> [options]

By default the zip is written to <ref>.zip in the current directory. Use --output to choose the path, or -o - to stream the zip to stdout.

Options:

FlagDescription
-o, --output <path>Output file path. Defaults to <ref>.zip (- streams to stdout)
--version <n|latest>Download the exact file uploaded for that version instead (CLI 1.14.0). See sharedrop versions
--jsonForce JSON output (errors only, except with --version)

Examples:

sharedrop download ubbsrh8rwx                 # writes ubbsrh8rwx.zip
sharedrop download ubbsrh8rwx -o report.zip   # write to a specific path
sharedrop download ubbsrh8rwx -o - > out.zip  # stream to stdout
sharedrop download ubbsrh8rwx --version 2     # version 2 as uploaded, e.g. ubbsrh8rwx-v2.pdf

You can download a page you own, or one shared to you with download enabled: the sharer ticks "allow zip download" on your access grant, matched against your account's verified email. A page you can't download returns the same not-found error as a page that doesn't exist, so existence is never leaked.

The default filename uses the ref you pass (<ref>.zip), not the page's slug, because the slug isn't known client-side without an extra lookup. Pass -o to set the name.

With --version, you get the file exactly as it was uploaded for that version (a folder upload as a zip), named as Sharedrop names it (<slug>-v<N>.<ext>) unless you pass -o. It streams to disk. You need version access on the page, as for sharedrop versions. With --json, or when the output is piped, it prints {"data":{"id":"ubbsrh8rwx","version":2,"path":"ubbsrh8rwx-v2.pdf","filename":"ubbsrh8rwx-v2.pdf","size_bytes":48213}}, where id is the ref you passed and version is the number you asked for (or "latest"). sharedrop -V, or sharedrop --version before any command (also after --url or --token), still prints the CLI version.


sharedrop versions

List a page's versions, the current one first (CLI 1.14.0). You need version access on the page: you own it, or it is in a workspace you belong to (as an owner, member or viewer). A page only shared with you fails with not found (exit code 5).

sharedrop versions <id>

On a terminal it prints a table with each version's number, kind, size, date and whether its original upload was kept. With --json, or when the output is piped, it prints the API response as {"data":[...]}.

sharedrop versions ubbsrh8rwx
sharedrop versions ubbsrh8rwx --json | jq '.data[] | select(.has_original) | .version'
sharedrop download ubbsrh8rwx --version 1

sharedrop update

Update a page's content, title, or visibility. Pass a file to replace the page's content, or a folder to replace a folder (bundle) page's files. The URL stays the same and the page's version goes up by one. Omit the file to change metadata only.

When you pass a file or folder, the output is the same as upload (see Upload JSON): was_reupload is true, version shows the new number, and warnings lists anything the sanitiser removed.

This works the same for a page in a workspace. You don't need --workspace: Sharedrop finds the page's workspace. The same goes for upload --page-id.

sharedrop update <id> [file] [options]

Options:

FlagDescription
--title <string>New page title
--visibility <string>public, private, or shared
--mode <string>static or interactive when replacing content (default: keep the page's current mode)
--slug <address>Rename a public page to a custom address (Pro plan or higher)
--jsonForce JSON output

Examples:

# Replace content -- same URL, new version recorded
sharedrop update 550e8400-... report.html

# Replace a folder page's files in place
sharedrop update 550e8400-... ./site

# Change metadata only
sharedrop update 550e8400-... --title "Updated Report" --visibility public

# Rename a public page to a custom address
sharedrop update 550e8400-... --slug quarterly-report

sharedrop delete

Move a page to recoverable, charged trash. Archives stay there for 7 days. Other pages stay for 30 days. Use sharedrop trash empty to permanently remove the authenticated caller's trash.

sharedrop delete <id> [options]

Options:

FlagDescription
--jsonForce JSON output

Example:

sharedrop delete 550e8400-e29b-41d4-a716-446655440000

sharedrop trash list

List the pages and folders in your trash, with their ids, so you can restore one with sharedrop folder restore <id>.

sharedrop trash list [options]

Options:

FlagDescription
--workspace <id|address>List a workspace's trash instead. An owner sees everything in it; a member sees what they deleted
--personalUse your personal space even when a default workspace is set
--jsonForce JSON output: { "items": [...] }

sharedrop trash empty

Permanently remove the authenticated caller's trash, or a workspace's, and release its charged storage. This operation is irreversible. The command itself is the destructive confirmation, so it works without a prompt in terminals, agents, and CI.

sharedrop trash empty [options]

Options:

FlagDescription
--workspace <id|address>Empty that workspace's trash; overrides the default workspace
--personalEmpty your personal trash even when a default workspace is set
--jsonReturn structured output with numeric purged and freedBytes fields

Examples:

sharedrop trash empty
sharedrop trash empty --workspace acme
sharedrop trash empty --json

Human output reports how many rows were purged and formats the released byte count. JSON output preserves the server response:

{
  "success": true,
  "purged": 3,
  "freedBytes": 1048576
}

Deleting an item does not immediately release storage. New uploads and archives compare live usage plus recoverable trash plus uploads still in progress plus the candidate bytes against the cap. Restore checks live usage plus only the selected trashed subtree. Archives stay in trash for 7 days. Other items, including folders, stay for 30 days.

Workspace storage meters and new-write gates charge all trash in the workspace. In a workspace's trash, an owner removes every item, a member only the items they created plus the trashed folders, and a viewer cannot empty it. A workspace-bound key with pages:write empties its own workspace; workspace:pages:write alone cannot empty it.


sharedrop move

Move an existing page into a folder, or back to the top level. Only the page's place in the tree changes: its URL, contents, and shares stay the same. Personal folders need a Pro plan or higher and workspace folders come with the Team plan; without them the command prints the server reason plus an upgrade link.

sharedrop move <id> (--folder <id|path> | --root)

Pass exactly one destination. --folder accepts a folder id or a slash path like reports/2026/q3, auto-creating any missing segments; --root sends the page back to your top level.

move needs no --workspace: it works in the page's own space. A workspace page's --folder path is found, and any missing folders created, in that workspace's folders; a personal page's in your personal folders. A folder id from another space prints A folder and its pages must be in the same space. and exits 6.

Options:

FlagDescription
--folder <id|path>Destination folder (id or slash path; missing segments are created)
--rootMove the page to your top level
--jsonForce JSON output

Examples:

sharedrop move ubbsrh8rwx --folder reports/q3   # into a folder (auto-created)
sharedrop move ubbsrh8rwx --root                # back to your top level

To file a page into a folder at upload time instead, use sharedrop upload <file> --folder <id|path>. To move a whole folder, use sharedrop folder move.


sharedrop share

Share a page with someone by email.

sharedrop share <id> --email <email> [options]

Options:

FlagDescription
--email <string>Email address to share with (required)
--jsonForce JSON output

Example:

sharedrop share 550e8400-... --email colleague@example.com

The recipient gets an invitation email, up to a daily limit per account: 10 on Free, 500 on Pro and 2000 on Team (this also counts link create --people emails). Over the limit the share still works, but no email is sent and the CLI prints a yellow line naming the limit, so send the link yourself. With --json the same message is in email_warning.


sharedrop shared

List the pages other people have shared with you, newest share first: the page ID, title, link, who shared it, when, and when the share ends. Copy the ID into get or fetch.

sharedrop shared [options]

Options:

FlagDescription
--limit <number>Results per page (default: 50, max 100)
--cursor <string>Pagination cursor
--jsonForce JSON output

Example:

$ sharedrop shared --limit 2
┌──────────────────────────────────────┬────────────┬─────────────────────────────────────────┬───────────┬────────────┬────────────┐
│ ID                                   │ Title      │ URL                                     │ Shared by │ Shared     │ Expires    │
├──────────────────────────────────────┼────────────┼─────────────────────────────────────────┼───────────┼────────────┼────────────┤
│ 550e8400-e29b-41d4-a716-446655440000 │ Q3 report  │ https://sharedrop.cloud/bob/q3abcd      │ bob       │ 20/10/2026 │ 20/11/2026 │
├──────────────────────────────────────┼────────────┼─────────────────────────────────────────┼───────────┼────────────┼────────────┤
│ 7c9e6679-7425-40de-944b-e07fc1f90ae7 │ Board deck │ https://sharedrop.cloud/ascend/deck12   │ carol     │ 19/10/2026 │            │
└──────────────────────────────────────┴────────────┴─────────────────────────────────────────┴───────────┴────────────┴────────────┘
More shares available. Use --cursor c0000000-0000-4000-8000-000000000002

With --json, or in a pipe, it prints {"data":[...],"pagination":{...}} with the same fields as GET /api/v1/shared. Shares belong to a person, so a workspace (sdw_) key is refused with exit code 3; use a personal key or sharedrop login.

If the share a --cursor points at has since been removed, the server refuses it with a 400 and the message "This cursor is no longer valid. Start again without a cursor." (exit code 6). Run sharedrop shared again without --cursor.


Manage disappearing links (Pro and Team): separate links that stop working after a time limit or a number of views. A link never changes the page's own visibility or sharing. See the Disappearing links guide.

sharedrop link create <id> [options]
sharedrop link list <id>
sharedrop link people <id> <link-id> [--add <emails...>] [--remove <emails...>]
sharedrop link revoke <id> <link-id>

<id> is the page id, slug, or full URL.

link create options:

FlagDescription
--people <emails...>Only these people can open the link, after signing in with one of these emails. Comma or space separated. Without it, anyone holding the link can open it
--expires-in <duration>Time limit, e.g. 30m, 12h, 7d (Pro up to 7 days, Team up to 30)
--max-views <n>Total views allowed across everyone
--presentSlide decks only: open straight into fullscreen Present mode
--no-emailWith --people: don't email them the link. link people --add takes it too
--jsonForce JSON output

Set --expires-in, --max-views, or both.

Examples:

# Anyone with the link, for 12 hours or 5 views
sharedrop link create q3-report --expires-in 12h --max-views 5

# Only the board, after they sign in
sharedrop link create q3-report --people board@example.com,cfo@example.com --expires-in 7d

# Add and remove people on that link
sharedrop link people q3-report <link-id> --add new@example.com --remove cfo@example.com

sharedrop link revoke q3-report <link-id>

Sharedrop emails the people on a --people link (and anyone added later) the link and its limits. Pass --no-email to send the URL the command prints yourself.


sharedrop reserve

Reserve a stable address before an agent has anything to upload. Prints the final URL plus a one-time claim token, then the agent claims it later with sharedrop upload <file> --to <slug>. See the Reserved addresses guide for the full walkthrough.

sharedrop reserve [options]

Options:

FlagDescription
--title <string>Page title shown once the address is claimed
--agent-name <name>Name of the agent expected to claim this address
--visibility <string>public, private, or shared the claimed page inherits (default private)
--slug <address>Pre-claim a custom address for a public reservation (Pro plan or higher)
--expires <timestamp>Expiry as an ISO 8601 timestamp. Omit to keep it until claimed or revoked
--workspace <id|address>Reserve the address in a workspace, by id or address. Claim it with sharedrop upload <file> --to <slug> --workspace <address>
--personalUse your personal space even when a default workspace is set
--jsonForce JSON output

The human output prints the reserved URL, status, and a Claim token with a "store this now, shown once, cannot be retrieved again" warning. Capture it immediately: the token appears only here, never in sharedrop reservations list. --json returns the reservation plus the sibling claim_token verbatim.

sharedrop reserve --title "Q3 Metrics" --agent-name "reporting-bot" --visibility public
sharedrop reserve --visibility public --slug quarterly-report

Claim it later with a single file:

sharedrop upload metrics.html --to abc123

--to accepts the reserved slug or the reservation id. The claim always creates a new page at the reserved URL, so it cannot be combined with --page-id (which replaces an existing page), --folder (the reservation keeps the folder chosen at reserve time), or a folder bundle (single file only). After the claim lands, re-upload over the live page with --page-id as normal.


sharedrop reservations

Manage your reserved addresses.

sharedrop reservations <subcommand> [options]

Subcommands:

CommandDescription
reservations listList your reserved addresses with their slug, status (reserved, claimed, expired, or revoked), intended agent, URL, and expiry. Accepts --limit, --cursor, --workspace <id|address> (a workspace's reservations) and --personal
reservations revoke <id>Revoke a reservation. The row is kept (status flips to revoked) and the claim token is permanently invalidated

All subcommands accept --json for structured output.

sharedrop reservations list
sharedrop reservations revoke 550e8400-e29b-41d4-a716-446655440000

sharedrop login

Authenticate with sharedrop via your browser.

sharedrop login

Opens your default browser to the sharedrop login page. After authenticating, a CLI-specific key is created and stored in your OS config directory (see Authentication for paths). Requires a TTY (interactive terminal). For headless/CI, set SHAREDROP_TOKEN instead.


sharedrop whoami

Show your account information.

sharedrop whoami [options]

Options:

FlagDescription
--jsonForce JSON output

Displays your username, email, plan, and usage information.

With a personal key the plan is your personal plan, for example Plan: Free (personal), and a Workspaces list shows each team workspace you belong to with its address, your role and your access (or Workspaces: none). With a workspace key (sdw_) it says which workspace the key is bound to and shows that workspace's plan. --json adds scope (personal or workspace), workspace and workspaces.

When a default workspace is active, a last line shows it and where it came from, for example Default workspace: ascend (Ascend Intelligence), set by `sharedrop workspaces use` . --json adds default_workspace: { "id", "slug", "source" } (source env, dotenv or saved), or null.


sharedrop workspaces

List the team workspaces you belong to. Each line shows the workspace name, its address, its id, your role and what you can do there. Pass the address (or the id) to --workspace on upload, check, archive, list, search, reserve, reservations list and trash list.

In the dashboard, Settings > Info shows the same details, plus your server address for --url or SHAREDROP_URL, with a copy button on each value. Copy for your agent copies them all as plain text, without any key.

sharedrop workspaces [options]

Options:

FlagDescription
--jsonForce JSON output
$ sharedrop workspaces
Ascend Intelligence  address: ascend  id: 6f1c2a9e-1b7d-4c52-9a51-0d3f8e2b7a10  role: owner  access: upload, edit all pages
Client Reports  address: client-reports  id: 0b8e4d3c-5a21-4f6e-8c97-2d1a6b9e4f30  role: member  access: upload, edit all pages
Partner Briefs  address: partner-briefs  id: 9d2f7b1a-3c84-4e5d-b6a0-7e1c5f8d2a49  role: viewer  access: read only

$ sharedrop upload report.html --workspace ascend

JSON output:

{
  "data": {
    "workspaces": [
      { "id": "6f1c2a9e-1b7d-4c52-9a51-0d3f8e2b7a10", "name": "Ascend Intelligence", "slug": "ascend", "role": "owner", "tier": "team", "can_upload": true, "can_edit_all_pages": true }
    ]
  }
}

What each role can do:

Roleaccess:can_uploadcan_edit_all_pages
ownerupload, edit all pagestruetrue
memberupload, edit all pagestruetrue
viewerread onlyfalsefalse

With no workspaces it says so: uploads go to your personal space. A workspace key (sdw_) sees only its own workspace. A workspace you are not a member of, on any --workspace, prints Workspace not found or you are not a member and exits 5.

The list ends with the active default workspace, if there is one, and --json adds default_workspace (as in whoami).

Default workspace

Save a workspace once instead of passing --workspace on every command:

sharedrop workspaces use <id|address>    # check you are a member, then save it
sharedrop workspaces use --clear         # remove it
$ sharedrop workspaces use ascend
Default workspace for sharedrop.cloud: Ascend Intelligence (address: ascend, id: 6f1c2a9e-1b7d-4c52-9a51-0d3f8e2b7a10)
Commands that take --workspace now use it. Pass --personal for your personal space.

--json prints { "data": { "default_workspace": { "id", "slug", "source": "saved" } } }; --clear --json prints default_workspace: null and cleared (true if one was saved). When SHAREDROP_WORKSPACE overrides the saved default, both add overridden_by (env or dotenv). A workspace you are not a member of prints Workspace not found or you are not a member, exits 5 and saves nothing.

The default is saved per server, so a default set with --url https://staging.example.com never applies to sharedrop.cloud. You can also set SHAREDROP_WORKSPACE (an id or address) in the environment or in a .env file in the current directory, like SHAREDROP_TOKEN.

Commands that take --workspace (upload, check, archive, list, search, reserve, reservations list, trash list, folder create, folder list) pick the workspace in this order, first match wins:

OrderSource
1--workspace <id|address>
2--personal (your personal space; passing it with --workspace exits 6)
3SHAREDROP_WORKSPACE environment variable
4SHAREDROP_WORKSPACE in .env
5The default saved with sharedrop workspaces use
6Your personal space
  • Other commands (get, update, delete, share, link, fetch, download, move, and folder rename, move, delete and restore) ignore the default: they act on the page's or folder's own space. A re-upload (upload --page-id, check --page-id) also ignores it: Sharedrop finds the page's own workspace. A claim (upload --to <slug>) looks the slug up in the default workspace (or personal with --personal), then Sharedrop files the page in the reservation's own workspace.
  • A workspace key (sdw_) always uses its own workspace. The default is ignored, with one note on stderr in text mode, and workspaces use with an sdw_ key exits 6 and saves nothing.
  • A default you no longer belong to fails with Workspace not found or you are not a member and exit 5. It never falls back to your personal space. Text mode adds a hint: run sharedrop workspaces use --clear or pass --personal.
  • Scripts and agents should pass --workspace explicitly, so the result does not depend on the machine. Use the default for interactive sessions.

sharedrop folder

Organise your pages into nested folders, in your personal space or in a team workspace. The folder command groups the full lifecycle: create, list, rename, move, delete (to trash), and restore. Personal folders need a Pro plan or higher; workspace folders come with the Team plan, whatever your personal plan. Without them the command prints the server reason plus Upgrade: https://sharedrop.cloud/pricing.

sharedrop folder <subcommand> [args] [options]

Subcommands:

CommandDescription
folder create <path>Create a folder. A slash path like reports/2026/q3 auto-creates each missing segment. --parent <id> nests under an existing folder in the same space. If the whole path already exists it prints an idempotent "already exists" line and exits 0. Takes --workspace and --personal
folder list [--parent <id>]List your top-level folders, or a folder's direct children. Takes --workspace and --personal
folder rename <id> <new-name>Rename a folder
folder move <id> (--parent <id> | --root)Reparent a folder, or move it to your top level with --root. Exactly one flag is required
folder delete <id> [--force]Delete a folder. An empty folder goes straight away; a non-empty one needs --force, which moves the subtree to trash and reports the page/folder counts affected. Archive descendants stay for 7 days; every other item stays for 30 days
folder restore <id>Restore a trashed folder or page before its kind-specific expiry. Restore checks live usage plus the selected subtree; if the original parent is gone, the item returns to your top level

All subcommands accept --json for structured output.

Examples:

sharedrop folder create reports/2026/q3        # nested, auto-creates segments
sharedrop folder list                          # top-level folders
sharedrop folder list --parent <folder-id>     # a folder's children
sharedrop folder rename <folder-id> "Q3 Reports"
sharedrop folder move <folder-id> --root       # back to top level
sharedrop folder delete <folder-id> --force    # non-empty: sends subtree to trash
sharedrop folder restore <folder-id>           # undo before kind-specific expiry
sharedrop folder create reports --workspace ascend   # a folder in a workspace
sharedrop folder list --workspace ascend             # a workspace's top-level folders

Workspace folders. folder create and folder list take --workspace <id|address> and --personal, and follow your default workspace. rename, move, delete and restore take a folder id and need no workspace: Sharedrop uses the folder's own space. Owners and members manage a workspace's folders; viewers can list them only. Owners and members can move or delete any workspace folder, whoever created the pages in it. A forced delete moves the folder and its pages to the workspace trash.

Personal folders need Pro and workspace folders need a Team workspace. Without them, folder commands (and --folder on upload/list/move) return a FOLDERS_RESTRICTED error with an upgrade link rather than silently falling back to the top level.


sharedrop about

Print what sharedrop is, why to use it, and the key links (docs, llms.txt, pricing). No authentication required.

sharedrop about [options]

Options:

FlagDescription
--jsonStructured output ({ "data": { "tagline", "why", "links" } }) for agents

Custom domains

If your account has a live custom domain, the CLI prints the branded address for any page that is eligible for it. upload, list, get and reservations all show https://share.yourcompany.com/yourhandle/abc123 instead of the sharedrop.cloud address, and --json carries the same value in full_url. A page in a Team workspace uses the workspace's custom domain, which the workspace owner manages.

Nothing about how you authenticate changes. The CLI still talks to sharedrop.cloud; only the URL it hands you for a recipient is branded. Pages that are not eligible, private pages and archives, keep their sharedrop.cloud address.

Custom domains cover public pages on subdomains only, and need exactly two records: one CNAME for share and one CNAME for view. See Custom domains for the full v1 scope.

CI/CD Usage

For CI/CD pipelines, use environment variables and JSON output:

export SHAREDROP_TOKEN=sd_your_api_key_here

# Upload a build artifact
sharedrop upload dist/report.html --title "Build #${BUILD_NUMBER}" --json

# Check exit code
if [ $? -eq 0 ]; then
  echo "Upload successful"
else
  echo "Upload failed"
fi

Key considerations for CI:

  • Set SHAREDROP_TOKEN as a secret in your CI provider
  • Use --json for machine-parseable output
  • Check exit codes for error handling (see Exit Codes)
  • No interactive prompts in non-TTY environments

Agent Usage

AI agents that shell out to CLIs can use sharedrop directly:

# Agent generates HTML and pipes it
cat file.html | sharedrop upload - --title "Agent Report" --json

# Parse the JSON response
URL=$(cat file.html | sharedrop upload - --json | jq -r '.data.full_url')

Agents should:

  • Always use --json for structured output
  • Use stdin (-) for piping generated HTML
  • Run sharedrop check first when it matters what the sanitiser removes or whether scripts will run
  • Read data.warnings, data.mode and data.scripts_will_run from the upload result instead of a second call
  • Revise a page with sharedrop update <id> <file> so the link stays the same; data.version goes up by one
  • Check exit codes for error handling
  • Use SHAREDROP_TOKEN environment variable for authentication
  • Pass --workspace <address> explicitly in scripts rather than relying on a default workspace