@dropthis/cli 0.1.5

package/README.md

@@ -0,0 +1,171 @@
+# Dropthis CLI
+
+Official CLI for Dropthis. Publish a file, folder, URL, stdin, or generated artifact and get a stable URL back.
+
+## For AI Agents
+
+Read [SKILL.md](./SKILL.md) and follow the instructions to publish with dropthis.
+
+## For Humans
+
+1. Copy the instruction above and send it to your AI agent.
+2. Your agent will install dropthis and ask for your email.
+3. Check your inbox for an OTP code and give it to your agent.
+4. Done — your agent can now publish pages for you.
+
+## Install
+
+```bash
+npm install -g dropthis
+```
+
+## Authentication
+
+The CLI resolves credentials in this order:
+
+1. `--api-key sk_...`
+2. `DROPTHIS_API_KEY`
+3. Stored credential from `dropthis login`
+
+For local development, override the API URL with `DROPTHIS_API_URL` or `--api-url`.
+
+```bash
+DROPTHIS_API_KEY=sk_live_... dropthis whoami --json
+```
+
+## Login
+
+Production login uses email OTP. Verification creates a durable API key through the SDK and stores it securely by default.
+
+```bash
+dropthis login request --email user@example.com --json
+dropthis login verify --email user@example.com --otp 123456 --json
+```
+
+You can also verify in one command after an OTP has already been requested:
+
+```bash
+dropthis login --email user@example.com --otp 123456 --json
+```
+
+Use `--insecure-storage` only when you explicitly accept plaintext credential storage.
+
+## Publish
+
+```bash
+dropthis publish ./site --json
+dropthis publish ./site --url
+dropthis publish https://example.com/demo.html --json
+dropthis publish - --content-type text/html --path index.html --json
+```
+
+## What You Can Publish
+
+Dropthis can publish single files, static sites, generated HTML, URLs, piped stdin, and multi-file bundles.
+
+```bash
+# A single HTML file
+dropthis publish report.html --title "Q4 Report" --json
+
+# A static site or app build
+dropthis publish ./dist --entry index.html --url
+
+# Multiple files as one bundled drop
+dropthis publish index.html styles.css app.js --json
+
+# A URL fetched by Dropthis
+dropthis publish https://example.com/demo.html --json
+
+# Generated HTML from stdin
+echo "<h1>Hello from Dropthis</h1>" | dropthis publish - --content-type text/html --path index.html --url
+
+# Generated JSON from stdin
+printf '{"status":"ok"}' | dropthis publish - --content-type application/json --path status.json --json
+
+# Validate before publishing
+dropthis publish ./dist --dry-run
+```
+
+For files and folders, content types are detected automatically. Use `--content-type` and `--path` when publishing stdin or generated content so the drop has the right MIME type and filename.
+
+`--url` prints only the URL and takes precedence over JSON, quiet mode, and TTY detection.
+
+`--dry-run` validates everything (auth, input detection, file collection) without calling the API. Outputs what would be published as JSON.
+
+Local files, folders, large stdin content, and explicit file inputs publish through staged uploads in the SDK. If `--idempotency-key` is omitted, content publish/update commands generate one automatically.
+
+Common publish options:
+
+```txt
+--title <title>
+--visibility <public|unlisted>
+--password <password>
+--no-password
+--noindex
+--index
+--expires-at <datetime>
+--metadata <json>
+--metadata-file <path>
+--entry <path>
+--content-type <mime>
+--path <path>
+--idempotency-key <key>
+```
+
+## Commands
+
+```bash
+dropthis publish <input>
+dropthis update <drop-id> [input]
+dropthis drops list --json
+dropthis drops get <drop-id> --json
+dropthis drops update <drop-id> --title "New title" --json
+dropthis drops delete <drop-id> --yes --json
+dropthis api-keys create --label CI --json
+dropthis api-keys list --json
+dropthis api-keys delete <key-id> --yes --json
+dropthis account get --json
+dropthis whoami --json
+dropthis doctor --json
+dropthis commands --json
+```
+
+## Output Modes
+
+Interactive TTY output is human-friendly. CI, pipes, non-TTY stdout, `--json`, and `--quiet` use JSON. Success writes to stdout. Errors write to stderr.
+
+Machine errors use stable exit codes:
+
+```txt
+0 success
+1 API or generic error
+2 invalid usage
+3 auth required
+4 local input error
+5 network error
+```
+
+## Examples
+
+The `examples/` directory contains ready-to-publish HTML files you can try:
+
+```bash
+# Publish the multi-step waitlist form
+dropthis publish examples/multi-step-form.html --title "Waitlist Form" --url
+```
+
+| File | Description | Live Demo |
+|------|-------------|-----------|
+| `multi-step-form.html` | Tally-style 4-step waitlist form with validation, transitions, and confetti | [View](https://d4b0mqc.dropthis.app/) |
+
+## Agent And CI Examples
+
+```bash
+dropthis commands --json
+dropthis publish ./dist --json
+dropthis update drop_01hzz00000000000000000 ./dist --if-revision 1 --json
+dropthis update drop_01hzz00000000000000000 --title "Final" --json
+dropthis deployments list drop_01hzz00000000000000000 --json
+dropthis deployments get drop_01hzz00000000000000000 dep_01hzz00000000000000000 --json
+DROPTHIS_API_KEY=$DROPTHIS_API_KEY dropthis doctor --json
+```