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. A CLI-specific API key is created and stored locally in ~/.config/sharedrop/. No copy-paste needed.

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 an HTML file to create a new page.

sharedrop upload <file> [options]

Arguments:

Argument	Description
file	Path to an HTML file, 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: static)
--workspace <id>	Upload to a specific workspace
--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.

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 get

Get details for a specific page.

sharedrop get <id> [options]

Options:

Flag	Description
--json	Force JSON output

Example:

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

---

sharedrop update

Update a page's title or visibility.

sharedrop update <id> [options]

Options:

Flag	Description
--title <string>	New page title
--visibility <string>	public, private, or shared
--json	Force JSON output

Example:

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 API key is created and stored locally. Requires a TTY (interactive terminal).

---

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.

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