uplink-cli 0.1.38 → 0.2.0

package/docs/AGENTS.md

@@ -1,195 +1,177 @@
 # Agent Integration Guide
 
-For agents (Cursor/Claude/GPT/Windsurf) to use Uplink non-interactively.
+For agents (Cursor, Claude Code, Codex, Windsurf, and similar) to use Uplink **non-interactively**.
+
+Install: `npm install -g uplink-cli` or `npx uplink-cli …`  
+Until **0.2.0** is on npm: `npm install -g github:firstprinciplecode/uplink#v0.2.0`  
+Package name: `uplink-cli` · Binary: `uplink`
 
 ## Auth
-- Use `AGENTCLOUD_TOKEN` (bearer). Avoid argv; prefer stdin:
+
+- `uplink tunnel create` automatically creates guest access when no token exists. Guest access includes **1 active tunnel**, expiring after **24 hours**.
+- Use `AGENTCLOUD_TOKEN` (bearer). Prefer stdin over argv:
   ```bash
-  echo "$TOKEN" | uplink --token-stdin ...
+  echo "$TOKEN" | uplink --token-stdin …
   ```
-- API base override: `--api-base https://api.uplink.spot` (or `AGENTCLOUD_API_BASE`).
+- Humans: `uplink login --email you@example.com` then `--code 123456`. This upgrades current guest access, preserves its tunnel, and unlocks persistent features. Credentials are saved to `~/.uplink/credentials` (chmod 600).
+- API base: `--api-base https://api.uplink.spot` or `AGENTCLOUD_API_BASE`.
+
+## Explicit guest token (optional)
 
-## Signup (no auth required)
 ```bash
 uplink signup --json
 uplink signup --label "cursor-agent" --expires-days 30 --json
 ```
-JSON example:
-```json
-{
-  "id": "tok_xxx",
-  "token": "abc123...",
-  "tokenPrefix": "abc123",
-  "role": "user",
-  "userId": "user_xxx",
-  "label": "cursor-agent",
-  "createdAt": "2025-01-01T00:00:00.000Z",
-  "expiresAt": "2025-01-31T00:00:00.000Z",
-  "message": "Token created successfully. Save this token securely..."
-}
+
+Save `token` from the JSON — it is shown only once. Then:
+
+```bash
+export AGENTCLOUD_TOKEN='…'
 ```
-Save `token`—shown only once.
+
+Explicit signup creates guest access. A later email login upgrades that guest account when the current token is available.
 
 ## Machine-mode contract
-- `--json` → stdout = JSON only; stderr = logs/errors.
-- Exit codes: 0 ok; 2 usage; 10 auth missing/invalid; 20 network; 30 server/unknown.
-- Premium alias gating: alias commands may return `ALIAS_NOT_ENABLED` / `ALIAS_LIMIT_REACHED`.
 
-## Core CLI flows (non-interactive)
+| Rule | Detail |
+|------|--------|
+| `--json` | stdout = JSON only; logs/errors go to stderr |
+| Exit `0` | success |
+| Exit `2` | usage / bad args |
+| Exit `10` | auth missing/invalid |
+| Exit `20` | network |
+| Exit `30` | server / unknown |
+
+Guest accounts can share one local port and use public domain search. Hosting, databases, aliases, and custom domains require a verified email account. Gate error: `ACCOUNT_VERIFICATION_REQUIRED`.
+
+Premium aliases may return `ALIAS_NOT_ENABLED` / `ALIAS_LIMIT_REACHED`.
+
+Free hosting (new accounts): **1 app**, **100 MB** of live artifacts, **no custom domains**, app **sleeps after 30 minutes idle**. Errors: `HOST_APP_LIMIT_REACHED`, `HOST_STORAGE_LIMIT_REACHED`, `HOST_DOMAIN_NOT_ENABLED`. Check quota: the `hosting` object on `GET /v1/me`.
+
+## Tunnels (share localhost)
+
+`tunnel create` **creates the API record and starts the local client** so the public URL works. Use `--api-only` only if you will start the client yourself.
+
 ```bash
-# Create tunnel (optional alias if enabled)
-echo "$TOKEN" | uplink --token-stdin --api-base https://api.uplink.spot \
+# Create + start client (optional alias if enabled)
+echo "$TOKEN" | uplink --token-stdin \
   tunnel create --port 3000 --alias myapp --json
 
-# List tunnels (includes connection status)
+# List (includes connected status)
 echo "$TOKEN" | uplink --token-stdin tunnel list --json
 
-# Set alias on tunnel
+# Alias on an existing tunnel
 echo "$TOKEN" | uplink --token-stdin tunnel alias-set --id tun_xxx --alias myapp --json
-
-# Delete alias from tunnel
 echo "$TOKEN" | uplink --token-stdin tunnel alias-delete --id tun_xxx --json
 
-# Stats
+# Stats / stop
 echo "$TOKEN" | uplink --token-stdin tunnel stats --id tun_xxx --json
-
-# Stop/delete tunnel
 echo "$TOKEN" | uplink --token-stdin tunnel stop --id tun_xxx --json
+echo "$TOKEN" | uplink --token-stdin tunnel stop --all --json
+```
+
+JSON create shape (representative):
+
+```json
+{
+  "tunnel": { "id": "tun_…", "url": "https://abc.x.uplink.spot", "token": "…", "status": "…" },
+  "alias": "myapp",
+  "aliasError": null,
+  "url": "https://myapp.uplink.spot",
+  "client": { "pid": 12345, "started": true }
+}
 ```
 
-## Hosting flows (non-interactive)
-Use `--json` for machine-mode output. For interactive prompts, pass `--yes`.
+`connected` on `tunnel list` means the local client is attached to the relay.
+
+## Hosting
+
+Use `--json`. For prompts, pass `--yes`.
 
 ```bash
-# Full setup (analyze + init + create + deploy)
 echo "$TOKEN" | uplink --token-stdin host setup \
-  --path /path/to/app \
-  --name myapp \
-  --env-file /path/to/.env \
-  --wait-timeout 900 \
-  --wait-interval 5 \
-  --yes \
-  --json
-
-# Deploy only (Dockerfile-based app)
+  --path /path/to/app --name myapp --env-file /path/to/.env \
+  --wait-timeout 900 --wait-interval 5 --yes --json
+
 echo "$TOKEN" | uplink --token-stdin host deploy \
-  --path /path/to/app \
-  --name myapp \
-  --env-file /path/to/.env \
-  --wait \
-  --wait-timeout 900 \
-  --wait-interval 5 \
-  --json
-
-# Analyze project
-echo "$TOKEN" | uplink --token-stdin host analyze --path /path/to/app --json
+  --path /path/to/app --name myapp --wait --json
 
-# List hosted apps
+echo "$TOKEN" | uplink --token-stdin host analyze --path /path/to/app --json
+echo "$TOKEN" | uplink --token-stdin host preflight --path /path/to/app --json
 echo "$TOKEN" | uplink --token-stdin host list --json
-
-# Status + logs
 echo "$TOKEN" | uplink --token-stdin host status --id app_xxx --json
 echo "$TOKEN" | uplink --token-stdin host logs --id app_xxx --json
-
-# Delete app
 echo "$TOKEN" | uplink --token-stdin host delete --id app_xxx --yes --json
 ```
 
 Notes:
-- `host logs` returns `NOT_READY` until a deployment is running.
-- If builds stay `queued`, check builder/runner services and build logs on the server.
-- For Prisma apps, ensure the Dockerfile copies `prisma/schema.prisma` before `npm ci` and runs `npx prisma generate` before `npm run build`.
-- Use a `.uplinkignore` file to keep tarballs small. Typical entries include `node_modules`, `.next`, `dist`, `build`, `coverage`, `.turbo`, `.cache`, `.vercel`, `*.log`, and any local SQLite `.db` files.
-- `host list` (non-JSON) prints two lines per app: `- name (app_id)` and the URL on the next line.
-- `host delete` requires typing `DELETE` unless `--yes` is provided.
-- Hosting output modes: Next.js expects `output: "standalone"` for server builds. Vite and CRA are treated as static builds (dist/build).
-
-## Interactive menu notes
-- All selection lists use arrow keys + Enter (no numeric entry required).
-- Hosted app lists display the app URL alongside name and ID.
-
-### JSON shapes (representative)
-- Create: `{ "tunnel": { id, url?, token?, alias?, aliasUrl?, targetPort, status, connected?, createdAt }, "alias": "myapp"|null, "aliasError": "..."|null }`
-- List: `{ "tunnels": [ { id, url?, token?, alias?, aliasUrl?, targetPort, status, connected, createdAt } ], "count": n }`
-- Stats: alias tunnels include persisted totals + relay overlay; token-only tunnels show in-memory relay stats.
-
-**Note:** The `connected` field indicates whether the tunnel is actually connected to the relay server (verified via socket health check).
-
-## HTTP API Reference
-
-Auth: `Authorization: Bearer <AGENTCLOUD_TOKEN>`
-
-### Tunnels
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `POST` | `/v1/tunnels` | Create tunnel (body: `{ port, alias? }`) |
-| `GET` | `/v1/tunnels` | List user's tunnels (includes `connected` status) |
-| `GET` | `/v1/tunnels/{id}` | Get tunnel details |
-| `GET` | `/v1/tunnels/{id}/stats` | Get tunnel statistics |
-| `DELETE` | `/v1/tunnels/{id}` | Delete tunnel |
-| `POST` | `/v1/tunnels/{id}/alias` | Set alias on tunnel (body: `{ alias }`) |
-| `DELETE` | `/v1/tunnels/{id}/alias` | Remove alias from tunnel |
-
-### Port-Based Aliases (Premium)
-Aliases are now **port-based**: they persist across tunnel restarts and always point to the same port.
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `GET` | `/v1/tunnels/aliases` | List all aliases for user |
-| `POST` | `/v1/tunnels/aliases` | Create alias for port (body: `{ alias, port }`) |
-| `PUT` | `/v1/tunnels/aliases/{alias}` | Reassign alias to different port (body: `{ port }`) |
-| `DELETE` | `/v1/tunnels/aliases/{alias}` | Delete alias |
-
-### Example: Create port-based alias
-```bash
-curl -X POST https://api.uplink.spot/v1/tunnels/aliases \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"alias": "myapp", "port": 3000}'
-```
+- Next.js server hosting expects `output: "standalone"`. Vite/CRA → static `dist`/`build`.
+- Prefer a `.uplinkignore` (`node_modules`, `.next`, `dist`, `*.log`, local `.db`, …).
+- `host logs` may return `NOT_READY` until a deployment is running.
+- `host delete` requires `--yes` (or typing `DELETE` interactively).
 
-Response:
-```json
-{
-  "id": "alias_xxx",
-  "alias": "myapp",
-  "targetPort": 3000,
-  "url": "https://myapp.uplink.spot",
-  "createdAt": "2025-01-03T00:00:00.000Z"
-}
+## Custom domains
+
+Registrar inventory is CLI. Attach/verify is under `host domains`.  
+The bare `uplink domains` search TUI is **optional** and not bundled with npm — use the JSON commands below.
+
+```bash
+uplink domains providers connect godaddy --token-env GODADDY_PAT --json
+uplink domains providers connect cloudflare --token-env CF_API_TOKEN --json
+uplink domains providers connect hostinger --token-env HOSTINGER_API_TOKEN --json
+uplink domains providers connect dreamhost --token-env DREAMHOST_API_KEY --json
+uplink domains providers connect namecheap --token-env NAMECHEAP_API_KEY --user-env NAMECHEAP_API_USER --json
+uplink domains providers list --json
+uplink domains providers disconnect godaddy --json
+
+uplink domains list --json
+uplink domains check example.com --json
+
+echo "$TOKEN" | uplink --token-stdin host domains add --id app_xxx --hostname example.com --json
+echo "$TOKEN" | uplink --token-stdin host domains verify --id app_xxx --hostname example.com --json
+echo "$TOKEN" | uplink --token-stdin host domains list --id app_xxx --json
+echo "$TOKEN" | uplink --token-stdin host domains remove --id app_xxx --hostname example.com --json
 ```
 
-## Domains
-- Public tunnels: `https://<token>.x.uplink.spot`
-- Permanent URLs (aliases): `https://<alias>.uplink.spot`
+`domains check` works without a registrar: it falls back to public DNS/RDAP and returns `provider: "public"` with no price. Do not treat RDAP “available” as buyable unless `domains check` says `buyable: true`. Purchase is not wired yet.
 
-## Server Deployment (for self-hosted)
-Control plane + hosting runtime live in the private repo `uplink-hosting-runtime`.
+## Databases (optional)
 
-### Deploy code changes
 ```bash
-# On server (via SSH)
-cd /opt/uplink-hosting-runtime
-git pull origin main
-systemctl restart backend-api
-systemctl restart tunnel-relay
-systemctl restart uplink-builder uplink-runner uplink-router  # if hosting runtime changed
+echo "$TOKEN" | uplink --token-stdin db create --name mydb --project myproj --json
+echo "$TOKEN" | uplink --token-stdin db list --json
+echo "$TOKEN" | uplink --token-stdin db info --id db_xxx --json
+echo "$TOKEN" | uplink --token-stdin db delete --id db_xxx --yes --json
 ```
 
-### Services
-| Service | Command | Description |
-|---------|---------|-------------|
-| `backend-api` | `systemctl status backend-api` | REST API server |
-| `tunnel-relay` | `systemctl status tunnel-relay` | WebSocket relay for tunnels |
-| `uplink-builder` | `systemctl status uplink-builder` | Builds Docker images |
-| `uplink-runner` | `systemctl status uplink-runner` | Runs containers |
-| `uplink-router` | `systemctl status uplink-router` | Routes host domains |
-
-### Relay health check
-The relay exposes internal endpoints (protected by `RELAY_INTERNAL_SECRET`):
-- `/internal/connected-tokens` - List connected tunnel tokens (with socket health verification)
-- `/internal/traffic-stats` - Traffic statistics by token/alias
-- `/health` - Basic health check
-
-## Optional JS helper
-Use `cli/src/agents/tunnels-client.ts` for the same retry/timeout behavior as the CLI.
+## Failure modes agents should expect
+
+| Symptom | Likely cause |
+|---------|----------------|
+| URL 502 / not connected | Local process on `--port` not running, or client died — re-run `tunnel create` or check `tunnel list` |
+| Auth errors | Missing/invalid `AGENTCLOUD_TOKEN`; use `--token-stdin` |
+| `ALIAS_NOT_ENABLED` | Account does not have permanent aliases |
+| Domain search TUI missing | Expected on npm — use `domains list` / `check` / `host domains *` |
+| `HOST_APP_LIMIT_REACHED` | Free plan is 1 hosted app — delete one or the account needs hosting granted |
+| `HOST_STORAGE_LIMIT_REACHED` | Upload exceeds the 100 MB free hosting budget |
+| `HOST_DOMAIN_NOT_ENABLED` | Custom domains are paid — `*.host.uplink.spot` still works |
+| First request after idle is slow | Free apps sleep after 30 minutes; the router wakes them |
+| Hosting stuck `queued` | Edge builder/runner issue — check `host status` / `host logs` |
+
+## Interactive menu
+
+Humans: `uplink` or `uplink menu` (Share · Hosting · Domains).  
+Agents should prefer the non-interactive commands above.
+
+## URLs
+
+- Ephemeral tunnels: `https://<token>.x.uplink.spot`
+- Aliases: `https://<alias>.uplink.spot`
+
+## More
+
+- Menu map: `docs/MENU_STRUCTURE.md`
+- Hosting: `docs/HOSTING.md`
+- Product: `docs/PRODUCT.md`
+- Website: https://uplink.spot
+- npm: https://www.npmjs.com/package/uplink-cli (0.2.0 pending; use the GitHub tag until then)

package/docs/HOSTING.md

@@ -0,0 +1,55 @@
+# Hosting
+
+Verified accounts can deploy apps to `*.host.uplink.spot`. Guests cannot — the API returns `ACCOUNT_VERIFICATION_REQUIRED`.
+
+## Commands
+
+```bash
+echo "$TOKEN" | uplink --token-stdin host setup --path . --name myapp --yes --json
+echo "$TOKEN" | uplink --token-stdin host deploy --path . --name myapp --wait --json
+echo "$TOKEN" | uplink --token-stdin host list --json
+echo "$TOKEN" | uplink --token-stdin host status --id app_xxx --json
+echo "$TOKEN" | uplink --token-stdin host logs --id app_xxx --json
+echo "$TOKEN" | uplink --token-stdin host delete --id app_xxx --yes --json
+```
+
+Public URL is `https://<app_id>.host.uplink.spot` (the app **id**, not the name). Custom hostnames attach with `host domains add` / `verify`.
+
+## What gets deployed
+
+- Next.js (App Router): `output: "standalone"` in `next.config`.
+- Vite / CRA: static `dist` or `build`.
+- Anything else: a `Dockerfile` in the project root.
+
+Use a `.uplinkignore` so `node_modules`, `.next`, `dist`, logs, and local databases are not uploaded.
+
+## Free-plan quotas
+
+From `GET /v1/me` → `hosting`:
+
+| Limit | Typical free account |
+|-------|----------------------|
+| Apps | 1 |
+| Live artifacts | 100 MB |
+| Custom domains | off (`HOST_DOMAIN_NOT_ENABLED`) |
+| Idle sleep | 30 minutes with no traffic |
+
+The platform URL still works when custom domains are gated.
+
+## Sleep and wake
+
+After idle timeout the runner stops the container and keeps the image. Status is `sleeping`, not deleted.
+
+The next HTTPS request to the app URL (or a verified custom domain) tells the router to wake it. Expect ~1–4 seconds on first hit, then normal latency.
+
+`host list` still shows sleeping apps. `host status` is where you see `running` vs `sleeping`.
+
+## Errors
+
+| Code | Meaning |
+|------|---------|
+| `ACCOUNT_VERIFICATION_REQUIRED` | Guest token — run `uplink login` |
+| `HOST_APP_LIMIT_REACHED` | Delete an app or raise the plan |
+| `HOST_STORAGE_LIMIT_REACHED` | Artifact too large |
+| `HOST_DOMAIN_NOT_ENABLED` | Custom domain not on this plan |
+| `NOT_READY` | Logs/status before a deployment is running |