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 -- 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:

OS	Path
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.

Exit Codes

Code	Meaning
0	Success
1	General error
2	Authentication required (no token found)
3	Authentication failed (invalid or revoked token)
4	Rate limited (429 from API)
5	Not found (404 from API)
6	Validation error (bad input)

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, and images (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.

sharedrop upload <file> [options]

Arguments:

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

Options:

Flag	Description
--title <string>	Page title (default: extracted from HTML <title>)
--visibility <string>	public, private, or shared (default: private)
--mode <string>	static or interactive, HTML only (default: static)
--entry <file>	Entry HTML for a folder/bundle upload, relative to the folder (default: index.html)
--workspace <id>	Upload to a specific workspace
--folder <id|path>	File the new page into a folder in your Sharedrop tree (Pro plan or higher). Accepts a folder id or a slash path like reports/q3, auto-creating missing segments. 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
--json	Force JSON output

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.

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 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:

Flag	Description
--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)
--workspace <id>	Upload to a specific workspace
--store-as-file	Store any file as a download-only archive, bypassing the archive-extension check (for a large non-archive file)
--json	Force 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>, and remove it with sharedrop delete <id>. 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:

Flag	Description
--limit <number>	Results per page (default: 50, max 100)
--cursor <string>	Pagination cursor
--workspace <id>	Filter to a specific workspace
--folder <id|path>	List the pages inside a folder (id or existing slash path)
--json	Force JSON output

Example:

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

---

sharedrop search

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:

Flag	Description
--limit <number>	Results per page (default: 50, max 100)
--cursor <string>	Pagination cursor
--workspace <id>	Search within a specific workspace
--json	Force 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 -- whatever's easiest to paste. The same applies to update, delete, and share.

Options:

Flag	Description
--json	Force 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:

Flag	Description
-o, --output <path>	Write the bytes to a file (- for stdout, the default)
--json	Force 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.

---

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:

Flag	Description
-o, --output <path>	Output file path -- defaults to <ref>.zip (- streams to stdout)
--json	Force JSON output (errors only)

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

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 -- the slug isn't known client-side without an extra lookup. Pass -o to set the name.

---

sharedrop update

Update a page's content, title, or visibility. Pass a file to replace the page's content -- the URL stays the same and a new version is recorded (re-versioning). Omit the file to change metadata only.

sharedrop update <id> [file] [options]

Options:

Flag	Description
--title <string>	New page title
--visibility <string>	public, private, or shared
--mode <string>	static or interactive (when replacing content)
--json	Force JSON output

Examples:

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

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

---

sharedrop delete

Delete a page permanently.

sharedrop delete <id> [options]

Options:

Flag	Description
--json	Force JSON output

Example:

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

---

sharedrop move

Move an existing page into a folder, or back to your top level. Only the page's place in your tree changes: its URL, contents, and shares stay the same. Requires a Pro plan or higher (folders are Pro-gated); a free key 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.

Options:

Flag	Description
--folder <id|path>	Destination folder (id or slash path; missing segments are created)
--root	Move the page to your top level
--json	Force 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:

Flag	Description
--email <string>	Email address to share with (required)
--json	Force JSON output

Example:

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

---

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:

Flag	Description
--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)
--expires <timestamp>	Expiry as an ISO 8601 timestamp. Omit to keep it until claimed or revoked
--json	Force 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

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:

Command	Description
reservations list	List your reserved addresses with their slug, status (reserved, claimed, expired, or revoked), intended agent, URL, and expiry. Accepts --limit and --cursor
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:

Flag	Description
--json	Force JSON output

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

---

sharedrop folder

Organise your pages into nested folders. The folder command groups the full lifecycle: create, list, rename, move, delete (to trash), and restore. Requires a Pro plan or higher; a free key prints the server reason plus Upgrade: https://sharedrop.cloud/pricing.

sharedrop folder <subcommand> [args] [options]

Subcommands:

Command	Description
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. If the whole path already exists it prints an idempotent "already exists" line and exits 0
folder list [--parent <id>]	List your top-level folders, or a folder's direct children
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 whole subtree to trash for 30 days and reports the page/folder counts affected
folder restore <id>	Restore a trashed folder or page within the 30-day window. 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 within 30 days

Folders are Pro-gated. On a free key, folder commands (and --folder on upload/list/move) return a FOLDERS_RESTRICTED error with an upgrade link rather than silently falling back to your 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:

Flag	Description
--json	Structured output ({ "data": { "tagline", "why", "links" } }) for agents

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
• Check exit codes for error handling
• Use SHAREDROP_TOKEN environment variable for authentication