handoff-ship

Deliver a static site to your client in one command.

npx handoff-ship ./dist --to "Maria"
# ✓ Uploaded "acme-roofing" (480 KB zip)
# ✓ Client link:  https://handoff.yourdomain.com/h/AbC123...

Upload a build directory to your Handoff account and get a client delivery link. Your client opens it, picks a domain, presses Launch — the site goes live on your Cloudflare. They never see DNS, hosting, or deploy.

Setup

1. Create a deploy token in your Handoff dashboard → API tokens.
2. Either:
   • npx handoff-ship login (prompts for the token + base URL, stores in ~/.handoffrc), or
   • set the env vars HANDOFF_TOKEN and HANDOFF_BASE.

Use

handoff-ship ./dist --name "Acme Roofing" --to "Maria" --email [email protected] --domain acmeroofing.com
handoff-ship sites        # list your sites
handoff-ship handoffs     # list your client links

In CI (GitHub Actions)

Store the token as the repo secret HANDOFF_TOKEN, set HANDOFF_BASE to your Handoff URL, and use the Handoff Action:

- uses: actions/checkout@v4
- run: npm ci && npm run build
- uses: your-org/handoff-action@v1
  with:
    dir: ./dist
    name: "Acme Roofing"
    to: "Maria"
  env:
    HANDOFF_TOKEN: ${{ secrets.HANDOFF_TOKEN }}
    HANDOFF_BASE: https://handoff.yourdomain.com

Security

• The token is deploy-scoped: it can upload sites + create handoff links + list them. It cannot read your Cloudflare token, change billing, register domains, or delete your account — those stay dashboard-login-only.
• The token is never logged. ~/.handoffrc is written mode 0600.
• Bases must be HTTPS (localhost is allowed for local dev); the token never crosses a plaintext wire.

Options

handoff-ship <dir>      # implicit deploy — the dir is the first arg
  --name <string>     site name (default: directory name)
  --to <name>         client name
  --email <addr>      client email (optional)
  --domain <domain>   pre-fill the client's domain (optional)
  --base <url>        Handoff base URL (default: HANDOFF_BASE env / ~/.handoffrc)
  --token <tok>       API token (default: HANDOFF_TOKEN env / ~/.handoffrc)
  --output <file>     write the client link to a file (CI: --output url.txt)
  --verbose           progress to stderr

Requires Node 18+. License: MIT.