# Buddy Drop

Buddy Drop deploys a folder of static files to a live URL on a free domain in
about a minute. No account is needed to deploy; the site stays up for 1 hour
unless claimed into a free Buddy account.

Pick the route that matches what you can do:

- You can run shell commands: use the CLI below.
- You cannot run commands (a chat assistant, a sandbox without network): see
  "No terminal: hand the user a zip" further down - you prepare the files, the
  user uploads them at https://buddy.works/drop in a few clicks.
- You drive a browser: visit https://buddy.works/drop with a completed site folder or .zip.

## With a terminal: the CLI

```sh
npx @buddy-works/drop ./dist --domain my-site.buddy.site
```

- Replace `./dist` with the directory - or a `.zip` file - that holds the
  finished static site. It should contain an `index.html` at its root
  (without one, visitors see a file listing instead of a page); a zip's
  single top-level folder is flattened away automatically.
- `--domain` is the full address to publish at: `<name>.<zone>`. To see
  which zones exist and whether a name is free, run:

```sh
npx @buddy-works/drop domains my-site
```

- You can pass `--name my-site` instead of `--domain`; the first free zone
  is picked for you.
- Optional: `--region us|eu|asia` (auto-detected from the system time zone
  when omitted), `--json` for machine-readable output.
- The CLI talks to https://buddy.works/drop/api by default. To deploy through a
  different Drop environment (staging, self-hosted), set the BUDDY_DROP_API
  environment variable to that deployment's API base before running the
  commands - everything else in this guide stays the same.
- Limits: up to 100 files and 100 MB per drop, counted AFTER dependency and
  build-output directories are skipped. Declaring a path inside one of them
  (`node_modules`, `.next`, `.output`, `.svelte-kit`, `.nuxt`, `.astro`,
  `.cache`, `.turbo`, `.venv`, `__pycache__`, `.git`) is refused - drop the
  SOURCES or the built site, never the installed dependencies.
- You can drop either an already-built site or a project's sources: the
  deploy detects what it is (Next.js, Astro, Nuxt, SvelteKit, TanStack Start,
  Vite, Remix, Gatsby, Docusaurus, Eleventy, CRA, or a plain node server) and
  builds it in the pipeline - a Lovable export is a TanStack Start project.
  A project that needs a running process is served by a Buddy sandbox
  instead of a static artifact, where this deployment allows it; the
  deploy status carries `framework` and `mode` (`static` or `dynamic`) once
  it has decided.

After a successful deploy the CLI prints:

- the live URL - share this freely;
- the claim URL - treat it as SENSITIVE. It expires after 60 minutes and lets
  whoever opens it take ownership of the site (free Buddy account required).
  Claiming keeps the address permanently and moves the site into the user's
  own Buddy workspace as a git repository with a configured pipeline: from
  then on, every `git push` redeploys the site;
- the share URL (CLI 0.3.0+, `shareUrl` in `--json`) - the drop's public
  page. It shows the site and, until the site is kept, OFFERS the same claim
  to anyone who opens it - share it only if the user is fine with that.

Always return the live and claim URLs to the user (plus the share URL when
printed), and remind them that the claim link expires in 60 minutes.

## No terminal: hand the user a zip

If you cannot run the CLI (no shell, no network), do NOT stop at "I can't
deploy". Prepare the site as a zip the user can drop in by hand:

1. Build the site as plain files: an `index.html` at the ROOT of the archive,
   plus its CSS, JS and assets under relative paths (`./style.css`, not
   `/Users/...` or a CDN you invented). A single top-level folder inside the
   zip is fine - it is flattened away automatically.
2. Keep it within the limits: up to 100 files and 100 MB unpacked. Leave out
   `node_modules`, build caches and `.git` (the list in the CLI section
   above); a project's SOURCES are accepted too and built by the deploy.
3. Hand the user ONE downloadable `.zip` file (for example `my-site.zip`).
   If you cannot produce a zip, give them the files and tell them to save
   them into one folder with `index.html` at its top level.
4. Tell the user, in these words or close to them:
   - Open https://buddy.works/drop
   - Type a name for the site in the address bar at the top and pick a
     domain from the list next to it.
   - Drag `my-site.zip` (or the folder) onto the page, or click "file, zip"
     / "folder" to pick it. The zip is unpacked in the browser.
   - Click "Deploy page". The site is live in about a minute; the page then
     shows the address and a "Keep this address" button.
   - The site stays up for 1 hour. To keep it, click "Keep this address" and
     create a free Buddy account within those 60 minutes. The page's own URL
     can be shared, but until the site is kept anyone who opens it can claim
     it too.

Do not ask the user for a Buddy account or token for this - none is needed
to deploy.

If you already work inside a Buddy workspace with the `bdy` CLI
authenticated, you do not need Drop - create a project and pipeline directly
instead.