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 checks for credentials in this order:

1. SHAREDROP_TOKEN environment variable -- Highest priority. Best for CI/CD.
2. .env file in the current directory -- Project-level config.
3. Stored credentials from sharedrop login -- Interactive browser-based auth.

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: based on plan)
--mode <string>	static or interactive (default: your account's default upload mode, initially interactive; configure in Settings)
--workspace <id>	Upload to a specific workspace
--page-id <id>	Re-upload over an existing page: keeps the same URL and records a new version
--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

---

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
--json	Force JSON output

Example:

sharedrop list --limit 10

---

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