uplink-cli 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,205 @@
+# Uplink
+
+**Localhost to public URL in seconds.** No browser, no signup forms, no friction.
+
+Uplink lets you expose your local dev server to the internet with a single command. Everything happens in your terminal—create an account, get a token, start a tunnel. Done.
+
+Perfect for sharing work-in-progress, testing webhooks, or demoing to clients. And because it's 100% CLI-based, AI coding assistants like **Cursor**, **Claude Code**, and **Windsurf** can set it up for you automatically.
+
+![Uplink CLI](./assets/cli-screenshot.png)
+
+## Features
+
+- **Instant Public URLs** - Your `localhost:3000` becomes `https://xyz.t.uplink.spot`
+- **Zero Browser Required** - Signup, auth, and tunnel management all in terminal
+- **Agent-Friendly** - AI assistants can create tokens and start tunnels via API
+- **Auto Port Detection** - Scans for running servers, select with arrow keys
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -g uplink-cli
+# Or run without global install:
+npx uplink-cli
+```
+
+### 2. Run Uplink
+
+```bash
+uplink
+```
+
+This opens an interactive menu. If you don't have a token yet, you'll see:
+
+```
+├─ Get Started (Create Account)
+└─ Exit
+```
+
+### 3. Create Your Account
+
+1. Select **"Get Started (Create Account)"**
+2. Enter an optional label (e.g., "my-laptop")
+3. Optionally set expiration days (or leave empty for no expiration)
+4. Your token will be displayed **once** - save it securely
+5. The CLI will offer to automatically add it to your `~/.zshrc` or `~/.bashrc`
+
+After adding the token, run:
+```bash
+source ~/.zshrc  # or ~/.bashrc
+uplink
+```
+
+### 4. Start a Tunnel
+
+Once authenticated, select **"Manage Tunnels"** → **"Start Tunnel"**:
+
+- The CLI will scan for active servers on your local machine
+- Use arrow keys to select a port, or choose "Enter custom port"
+- Press "Back" if you want to cancel
+- Your tunnel URL will be displayed (e.g., `https://abc123.t.uplink.spot`)
+
+**Keep the terminal running** - the tunnel client must stay active.
+
+## CLI Commands
+
+### Interactive Menu (Recommended)
+
+```bash
+uplink
+# or
+uplink menu
+```
+
+### Direct Commands
+
+```bash
+# Start a tunnel for port 3000
+uplink dev --tunnel --port 3000
+
+# List databases
+uplink db list
+
+# Create a database
+uplink db create --name mydb --region us-east-1
+
+# Admin commands (requires admin token)
+uplink admin status
+uplink admin tunnels
+uplink admin databases
+```
+
+## Environment Variables
+
+```bash
+# API endpoint (default: https://api.uplink.spot)
+export AGENTCLOUD_API_BASE=https://api.uplink.spot
+
+# Your API token (required)
+export AGENTCLOUD_TOKEN=your-token-here
+
+# Tunnel control server (default: tunnel.uplink.spot:7071)
+export TUNNEL_CTRL=tunnel.uplink.spot:7071
+
+# Tunnel domain (default: t.uplink.spot)
+export TUNNEL_DOMAIN=t.uplink.spot
+```
+
+## Requirements
+
+- **Node.js** 20.x or later
+- **API Token** - Created automatically via signup, or provided by an admin
+
+## How It Works
+
+### Tunnel Service
+
+1. **Create tunnel** - Request a tunnel from the API
+2. **Get token** - Receive a unique token (e.g., `abc123`)
+3. **Start client** - Run the tunnel client locally, connecting to the relay
+4. **Access** - Your local server is accessible at `https://abc123.t.uplink.spot`
+
+The tunnel client forwards HTTP requests from the public URL to your local server.
+
+### Database Service
+
+Create and manage PostgreSQL databases via Neon. Databases are provisioned automatically and connection strings are provided.
+
+## Troubleshooting
+
+### "Connection refused" error
+- Make sure your local server is running on the specified port
+- Start your server first, then create the tunnel
+
+### "Cannot connect to relay" error
+- Verify the `TUNNEL_CTRL` address is correct
+- Check if the tunnel relay service is running
+
+### Tunnel URL returns "Gateway timeout"
+- Make sure the tunnel client is still running
+- Restart the tunnel client if it exited
+
+### Token not working
+- Verify `AGENTCLOUD_TOKEN` is set: `echo $AGENTCLOUD_TOKEN`
+- Make sure you ran `source ~/.zshrc` (or `~/.bashrc`) after adding the token
+- Create a new token if needed
+
+## API Endpoints
+
+The CLI communicates with the Uplink API. Main endpoints:
+
+- `POST /v1/signup` - Create account (public, no auth)
+- `POST /v1/tunnels` - Create tunnel
+- `GET /v1/tunnels` - List your tunnels
+- `DELETE /v1/tunnels/:id` - Delete tunnel
+- `POST /v1/databases` - Create database
+- `GET /v1/databases` - List your databases
+- `GET /v1/admin/stats` - System statistics (admin only)
+
+## Security
+
+### Token Security
+- Tokens are hashed with HMAC-SHA256 before storage (never stored in plain text)
+- Tokens can be revoked instantly or set to auto-expire
+- User tokens only see their own resources (tunnels, databases)
+- Admin tokens required for system-wide operations
+
+### Rate Limiting
+- Signup: 5 requests/hour per IP (strictest)
+- Authentication: 10 attempts/15 min per IP
+- API calls: 100 requests/15 min per IP
+- Token creation: 20/hour
+- Tunnel creation: 50/hour
+
+### Production Recommendations
+
+1. **Set a token pepper** (strongly recommended):
+   ```bash
+   export CONTROL_PLANE_TOKEN_PEPPER=your-random-secret-here
+   ```
+   This adds an extra layer of protection - even if the database is compromised, tokens can't be used without the pepper.
+
+2. **Disable dev tokens** in production:
+   - Don't set `AGENTCLOUD_TOKEN_DEV`
+   - Use only database-backed tokens
+
+3. **Break-glass admin access** (emergency only):
+   ```bash
+   export ADMIN_TOKENS=emergency-admin-token-1,emergency-admin-token-2
+   ```
+   These bypass the database - use only for emergencies and rotate after use.
+
+4. **Use HTTPS** for all API endpoints (handled by Caddy in production)
+
+## License
+
+MIT
+
+## Support
+
+For issues or questions, check:
+- Run `uplink` and use the interactive menu
+- Check environment variables are set correctly
+- Verify your token is valid: `uplink admin status` (if admin)

package/cli/bin/uplink.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * Uplink CLI entry point
+ * Defaults to menu if no command provided
+ */
+
+const { spawn } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+// Get paths
+const binDir = __dirname;
+const projectRoot = path.join(binDir, "../..");
+const cliPath = path.join(projectRoot, "cli/src/index.ts");
+
+// Get arguments
+const args = process.argv.slice(2);
+
+// If no command provided, default to menu
+// Otherwise pass through - commander will handle help/version/unknown commands
+if (args.length === 0) {
+  args.push("menu");
+}
+
+// Find tsx - prefer project-local, otherwise fall back to PATH
+let tsxPath = "tsx";
+try {
+  // Newer tsx exposes a CLI entry at dist/cli.cjs
+  tsxPath = require.resolve("tsx/dist/cli.cjs", { paths: [projectRoot] });
+} catch (e) {
+  try {
+    tsxPath = require.resolve("tsx/cli", { paths: [projectRoot] });
+  } catch (_) {
+    // keep fallback to PATH
+  }
+}
+
+// Run the CLI via tsx (no extra node wrapper so PATH/global tsx works)
+const child = spawn(tsxPath, [cliPath, ...args], {
+  stdio: "inherit",
+  cwd: projectRoot,
+  env: process.env,
+  shell: false,
+});
+
+child.on("error", (err) => {
+  console.error("Error running uplink:", err.message);
+  console.error("\nMake sure tsx is installed: npm install -g tsx");
+  process.exit(1);
+});
+
+child.on("exit", (code) => {
+  process.exit(code || 0);
+});
+

package/cli/src/http.ts

@@ -0,0 +1,60 @@
+import fetch from "node-fetch";
+
+function getApiBase(): string {
+  return process.env.AGENTCLOUD_API_BASE ?? "https://api.uplink.spot";
+}
+
+function isLocalApiBase(apiBase: string): boolean {
+  return (
+    apiBase.includes("://localhost") ||
+    apiBase.includes("://127.0.0.1") ||
+    apiBase.includes("://0.0.0.0")
+  );
+}
+
+function getApiToken(apiBase: string): string | undefined {
+  // Production (non-local) always requires an explicit token.
+  if (!isLocalApiBase(apiBase)) {
+    return process.env.AGENTCLOUD_TOKEN || undefined;
+  }
+
+  // Local dev convenience:
+  // - Prefer AGENTCLOUD_TOKEN if set
+  // - Otherwise allow AGENTCLOUD_TOKEN_DEV / dev-token
+  return (
+    process.env.AGENTCLOUD_TOKEN ||
+    process.env.AGENTCLOUD_TOKEN_DEV ||
+    "dev-token"
+  );
+}
+
+export async function apiRequest(
+  method: string,
+  path: string,
+  body?: unknown
+): Promise<any> {
+  const apiBase = getApiBase();
+  const apiToken = getApiToken(apiBase);
+  if (!apiToken) {
+    throw new Error("Missing AGENTCLOUD_TOKEN");
+  }
+
+  const response = await fetch(`${apiBase}${path}`, {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiToken}`,
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  const json = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error(JSON.stringify(json, null, 2));
+  }
+
+  return json;
+}
+
+
+

package/cli/src/index.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { dbCommand } from "./subcommands/db";
+import { devCommand } from "./subcommands/dev";
+import { adminCommand } from "./subcommands/admin";
+import { menuCommand } from "./subcommands/menu";
+
+const program = new Command();
+
+program
+  .name("uplink")
+  .description("Agent-friendly cloud CLI")
+  .version("0.1.0");
+
+program.addCommand(dbCommand);
+program.addCommand(devCommand);
+program.addCommand(adminCommand);
+program.addCommand(menuCommand);
+
+// If no command provided and not a flag, default to menu
+if (process.argv.length === 2) {
+  process.argv.push("menu");
+} else if (process.argv.length === 3 && process.argv[2] === "--help") {
+  // Show main help, not menu
+  process.argv.pop();
+}
+
+program.parseAsync(process.argv).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+

package/cli/src/subcommands/admin.ts

@@ -0,0 +1,351 @@
+import { Command } from "commander";
+import { apiRequest } from "../http";
+
+export const adminCommand = new Command("admin")
+  .description("Admin commands for system management");
+
+// Format date for display
+function formatDate(dateStr: string): string {
+  const date = new Date(dateStr);
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffMins = Math.floor(diffMs / 60000);
+  const diffHours = Math.floor(diffMs / 3600000);
+  const diffDays = Math.floor(diffMs / 86400000);
+
+  if (diffMins < 1) return "just now";
+  if (diffMins < 60) return `${diffMins}m ago`;
+  if (diffHours < 24) return `${diffHours}h ago`;
+  if (diffDays < 7) return `${diffDays}d ago`;
+  return date.toLocaleDateString();
+}
+
+// Status command
+adminCommand
+  .command("status")
+  .description("Show system status and statistics")
+  .option("--json", "Output JSON", false)
+  .action(async (opts) => {
+    try {
+      // Check health
+      const apiBase = process.env.AGENTCLOUD_API_BASE || "https://api.uplink.spot";
+      let health = { status: "unknown" };
+      try {
+        const fetch = (await import("node-fetch")).default;
+        const healthRes = await fetch(`${apiBase}/health`);
+        health = await healthRes.json();
+      } catch (err) {
+        // Health check failed, continue anyway
+      }
+
+      // Get stats
+      const stats = await apiRequest("GET", "/v1/admin/stats");
+
+      if (opts.json) {
+        console.log(JSON.stringify({ health, stats }, null, 2));
+      } else {
+        console.log("\n📊 System Status\n");
+        console.log(`API Health: ${health.status === "ok" ? "✅ OK" : "❌ Error"}`);
+        console.log("\n📈 Statistics\n");
+        console.log("Tunnels:");
+        console.log(`  Active:     ${stats.tunnels.active}`);
+        console.log(`  Inactive:   ${stats.tunnels.inactive}`);
+        console.log(`  Deleted:    ${stats.tunnels.deleted}`);
+        console.log(`  Total:      ${stats.tunnels.total}`);
+        console.log(`  Created 24h: ${stats.tunnels.createdLast24h}`);
+        console.log("\nDatabases:");
+        console.log(`  Ready:      ${stats.databases.ready}`);
+        console.log(`  Provisioning: ${stats.databases.provisioning}`);
+        console.log(`  Failed:     ${stats.databases.failed}`);
+        console.log(`  Deleted:    ${stats.databases.deleted}`);
+        console.log(`  Total:      ${stats.databases.total}`);
+        console.log(`  Created 24h: ${stats.databases.createdLast24h}`);
+        console.log();
+      }
+    } catch (error: any) {
+      const errorMsg = error.message || error.toString() || JSON.stringify(error);
+      console.error("Error getting status:", errorMsg);
+      process.exit(1);
+    }
+  });
+
+// Tunnels command
+adminCommand
+  .command("tunnels")
+  .description("List all tunnels")
+  .option("--status <status>", "Filter by status (active, inactive, deleted)")
+  .option("--limit <limit>", "Limit results", "20")
+  .option("--json", "Output JSON", false)
+  .action(async (opts) => {
+    try {
+      const query: string[] = [];
+      if (opts.status) query.push(`status=${encodeURIComponent(opts.status)}`);
+      if (opts.limit) query.push(`limit=${opts.limit}`);
+      const queryStr = query.length > 0 ? `?${query.join("&")}` : "";
+
+      const result = await apiRequest("GET", `/v1/admin/tunnels${queryStr}`);
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`\n🔗 Tunnels (showing ${result.count} of ${result.total})\n`);
+        if (result.tunnels.length === 0) {
+          console.log("No tunnels found.");
+        } else {
+          console.log(
+            "ID".padEnd(40) +
+            "Token".padEnd(14) +
+            "Port".padEnd(6) +
+            "Status".padEnd(10) +
+            "Created"
+          );
+          console.log("-".repeat(90));
+          for (const tunnel of result.tunnels) {
+            const id = tunnel.id.substring(0, 38);
+            const token = tunnel.token.substring(0, 12);
+            const port = String(tunnel.target_port || tunnel.targetPort || "-");
+            const status = tunnel.status || "unknown";
+            const created = formatDate(tunnel.created_at || tunnel.createdAt);
+            console.log(
+              id.padEnd(40) +
+              token.padEnd(14) +
+              port.padEnd(6) +
+              status.padEnd(10) +
+              created
+            );
+          }
+        }
+        console.log();
+      }
+    } catch (error: any) {
+      const errorMsg = error.message || error.toString() || JSON.stringify(error);
+      console.error("Error listing tunnels:", errorMsg);
+      process.exit(1);
+    }
+  });
+
+// Databases command
+adminCommand
+  .command("databases")
+  .description("List all databases")
+  .option("--status <status>", "Filter by status (ready, provisioning, failed, deleted)")
+  .option("--limit <limit>", "Limit results", "20")
+  .option("--json", "Output JSON", false)
+  .action(async (opts) => {
+    try {
+      const query: string[] = [];
+      if (opts.status) query.push(`status=${encodeURIComponent(opts.status)}`);
+      if (opts.limit) query.push(`limit=${opts.limit}`);
+      const queryStr = query.length > 0 ? `?${query.join("&")}` : "";
+
+      const result = await apiRequest("GET", `/v1/admin/databases${queryStr}`);
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`\n🗄️  Databases (showing ${result.count} of ${result.total})\n`);
+        if (result.databases.length === 0) {
+          console.log("No databases found.");
+        } else {
+          console.log(
+            "ID".padEnd(40) +
+            "Name".padEnd(20) +
+            "Provider".padEnd(12) +
+            "Region".padEnd(15) +
+            "Status".padEnd(12) +
+            "Created"
+          );
+          console.log("-".repeat(110));
+          for (const db of result.databases) {
+            const id = db.id.substring(0, 38);
+            const name = (db.name || "-").substring(0, 18);
+            const provider = (db.provider || "-").substring(0, 10);
+            const region = (db.region || "-").substring(0, 13);
+            const status = db.status || "unknown";
+            const created = formatDate(db.created_at || db.createdAt);
+            console.log(
+              id.padEnd(40) +
+              name.padEnd(20) +
+              provider.padEnd(12) +
+              region.padEnd(15) +
+              status.padEnd(12) +
+              created
+            );
+          }
+        }
+        console.log();
+      }
+    } catch (error: any) {
+      const errorMsg = error.message || error.toString() || JSON.stringify(error);
+      console.error("Error listing databases:", errorMsg);
+      process.exit(1);
+    }
+  });
+
+// Tokens command group
+const tokensCommand = adminCommand
+  .command("tokens")
+  .description("Manage API tokens (mint/list/revoke)");
+
+tokensCommand
+  .command("create")
+  .description("Mint a new token (returned once)")
+  .requiredOption("--role <role>", "Role: user|admin", "user")
+  .option("--label <label>", "Optional label (e.g. customer name)")
+  .option("--expires-days <days>", "Optional expiry in days (integer)")
+  .option("--json", "Output JSON", false)
+  .action(async (opts) => {
+    try {
+      const role = String(opts.role || "user");
+      const label = opts.label ? String(opts.label) : undefined;
+      const expiresInDays = opts.expiresDays ? Number(opts.expiresDays) : undefined;
+
+      const result = await apiRequest("POST", "/v1/admin/tokens", {
+        role,
+        label,
+        expiresInDays: Number.isFinite(expiresInDays as any) ? expiresInDays : undefined,
+      });
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+
+      console.log("\n🔑 Token created\n");
+      console.log(`Role:      ${result.role}`);
+      console.log(`User ID:    ${result.userId}`);
+      console.log(`Token ID:   ${result.id}`);
+      console.log(`Prefix:     ${result.tokenPrefix}`);
+      if (result.label) console.log(`Label:      ${result.label}`);
+      if (result.expiresAt) console.log(`Expires:    ${result.expiresAt}`);
+      console.log("\nIMPORTANT: This token is shown only once. Store it securely.\n");
+      console.log(result.token);
+      console.log();
+    } catch (error: any) {
+      const errorMsg = error.message || error.toString() || JSON.stringify(error);
+      console.error("Error creating token:", errorMsg);
+      process.exit(1);
+    }
+  });
+
+tokensCommand
+  .command("list")
+  .description("List tokens (no raw token values)")
+  .option("--limit <limit>", "Limit results", "50")
+  .option("--offset <offset>", "Offset", "0")
+  .option("--json", "Output JSON", false)
+  .action(async (opts) => {
+    try {
+      const limit = Number(opts.limit) || 50;
+      const offset = Number(opts.offset) || 0;
+      const result = await apiRequest(
+        "GET",
+        `/v1/admin/tokens?limit=${encodeURIComponent(String(limit))}&offset=${encodeURIComponent(
+          String(offset)
+        )}`
+      );
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+
+      console.log(`\n🪪 Tokens (showing ${result.count} of ${result.total})\n`);
+      if (!result.tokens || result.tokens.length === 0) {
+        console.log("No tokens found.");
+        return;
+      }
+
+      console.log(
+        "ID".padEnd(18) +
+          "Role".padEnd(8) +
+          "Prefix".padEnd(10) +
+          "User ID".padEnd(40) +
+          "Status".padEnd(12) +
+          "Created"
+      );
+      console.log("-".repeat(100));
+
+      for (const t of result.tokens) {
+        const id = String(t.id || "").slice(0, 16);
+        const role = String(t.role || "-").slice(0, 6);
+        const prefix = String(t.token_prefix || t.tokenPrefix || "-").slice(0, 8);
+        const userId = String(t.user_id || t.userId || "-").slice(0, 38);
+        const status = t.revoked_at || t.revokedAt ? "revoked" : "active";
+        const created = formatDate(t.created_at || t.createdAt || "");
+        console.log(
+          id.padEnd(18) +
+            role.padEnd(8) +
+            prefix.padEnd(10) +
+            userId.padEnd(40) +
+            status.padEnd(12) +
+            created
+        );
+      }
+      console.log();
+    } catch (error: any) {
+      const errorMsg = error.message || error.toString() || JSON.stringify(error);
+      console.error("Error listing tokens:", errorMsg);
+      process.exit(1);
+    }
+  });
+
+tokensCommand
+  .command("revoke")
+  .description("Revoke a token (prefer by id)")
+  .option("--id <id>", "Token id (recommended)")
+  .option("--token <token>", "Raw token (avoid: may end up in shell history)")
+  .option("--json", "Output JSON", false)
+  .action(async (opts) => {
+    try {
+      const id = opts.id ? String(opts.id) : "";
+      const token = opts.token ? String(opts.token) : "";
+      if (!id && !token) {
+        console.error("Provide --id or --token");
+        process.exit(1);
+      }
+
+      const result = await apiRequest("POST", "/v1/admin/tokens/revoke", {
+        id: id || undefined,
+        token: token || undefined,
+      });
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`✅ Revoked token${id ? ` ${id}` : ""} at ${result.revokedAt || ""}`);
+      }
+    } catch (error: any) {
+      const errorMsg = error.message || error.toString() || JSON.stringify(error);
+      console.error("Error revoking token:", errorMsg);
+      process.exit(1);
+    }
+  });
+
+// Cleanup command
+adminCommand
+  .command("cleanup")
+  .description("Cleanup old data")
+  .option("--dev-user-tunnels", "Clean up tunnels owned by dev-user", false)
+  .option("--json", "Output JSON", false)
+  .action(async (opts) => {
+    try {
+      if (opts.devUserTunnels) {
+        const result = await apiRequest("POST", "/v1/admin/cleanup/dev-user-tunnels", {});
+
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(`✅ ${result.message || `Cleaned up ${result.deleted || 0} dev-user tunnels`}`);
+        }
+      } else {
+        console.error("Specify what to cleanup: --dev-user-tunnels");
+        process.exit(1);
+      }
+    } catch (error: any) {
+      const errorMsg = error.message || error.toString() || JSON.stringify(error);
+      console.error("Error during cleanup:", errorMsg);
+      process.exit(1);
+    }
+  });
+