run402 1.2.0 → 1.3.0

package/cli.mjs

@@ -13,10 +13,16 @@ Usage:
   run402 <command> [subcommand] [options]
 
 Commands:
-  wallet    Manage your x402 wallet (create, fund, check status)
-  projects  Manage deployed projects (list, query, inspect, renew, delete)
-  deploy    Deploy a full-stack app or static site (Postgres + hosting)
-  image     Generate AI images via x402 micropayments
+  wallet      Manage your x402 wallet (create, fund, balance, status)
+  projects    Manage projects (provision, list, query, inspect, renew, delete)
+  deploy      Deploy a full-stack app or static site (Postgres + hosting)
+  functions   Manage serverless functions (deploy, invoke, logs, list, delete)
+  secrets     Manage project secrets (set, list, delete)
+  storage     Manage file storage (upload, download, list, delete)
+  sites       Deploy static sites
+  subdomains  Manage custom subdomains (claim, list, delete)
+  apps        Browse and manage the app marketplace
+  image       Generate AI images via x402 micropayments
 
 Run 'run402 <command> --help' for detailed usage of each command.
 
@@ -26,6 +32,8 @@ Examples:
   run402 deploy --tier prototype --manifest app.json
   run402 projects list
   run402 projects sql <project_id> "SELECT * FROM users LIMIT 5"
+  run402 functions deploy <project_id> my-fn --code handler.ts
+  run402 secrets set <project_id> API_KEY sk-1234
   run402 image generate "a startup mascot, pixel art" --output logo.png
 
 Getting started:
@@ -55,6 +63,36 @@ switch (cmd) {
     await run([sub, ...rest].filter(Boolean));
     break;
   }
+  case "functions": {
+    const { run } = await import("./lib/functions.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "secrets": {
+    const { run } = await import("./lib/secrets.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "storage": {
+    const { run } = await import("./lib/storage.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "sites": {
+    const { run } = await import("./lib/sites.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "subdomains": {
+    const { run } = await import("./lib/subdomains.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "apps": {
+    const { run } = await import("./lib/apps.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "image": {
     const { run } = await import("./lib/image.mjs");
     await run(sub, rest);

package/lib/apps.mjs

@@ -0,0 +1,137 @@
+import { existsSync } from "fs";
+import { findProject, readWallet, loadProjects, saveProjects, API, WALLET_FILE, PROJECTS_FILE } from "./config.mjs";
+import { mkdirSync, writeFileSync } from "fs";
+
+const HELP = `run402 apps — Browse and manage the app marketplace
+
+Usage:
+  run402 apps <subcommand> [args...]
+
+Subcommands:
+  browse  [--tag <tag>]                   Browse public apps
+  fork    <version_id> <name> [--tier <tier>] [--subdomain <name>]
+                                           Fork a published app into your own project
+  publish <id> [--description <desc>] [--tags <t1,t2>] [--visibility <v>] [--fork-allowed]
+                                           Publish a project as an app
+  versions <id>                            List published versions of a project
+
+Examples:
+  run402 apps browse
+  run402 apps browse --tag auth
+  run402 apps fork ver_abc123 my-todo --tier prototype
+  run402 apps publish proj123 --description "Todo app" --tags todo,auth --visibility public --fork-allowed
+  run402 apps versions proj123
+`;
+
+async function browse(args) {
+  let url = `${API}/v1/apps`;
+  const tags = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--tag" && args[i + 1]) tags.push(args[++i]);
+  }
+  if (tags.length > 0) url += "?" + tags.map(t => `tag=${encodeURIComponent(t)}`).join("&");
+  const res = await fetch(url);
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function fork(versionId, name, args) {
+  const opts = { tier: "prototype", subdomain: undefined };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--tier" && args[i + 1]) opts.tier = args[++i];
+    if (args[i] === "--subdomain" && args[i + 1]) opts.subdomain = args[++i];
+  }
+  if (!existsSync(WALLET_FILE)) {
+    console.error(JSON.stringify({ status: "error", message: "No wallet found. Run: run402 wallet create && run402 wallet fund" }));
+    process.exit(1);
+  }
+
+  const wallet = readWallet();
+  const { privateKeyToAccount } = await import("viem/accounts");
+  const { createPublicClient, http } = await import("viem");
+  const { baseSepolia } = await import("viem/chains");
+  const { x402Client, wrapFetchWithPayment } = await import("@x402/fetch");
+  const { ExactEvmScheme } = await import("@x402/evm/exact/client");
+  const { toClientEvmSigner } = await import("@x402/evm");
+  const account = privateKeyToAccount(wallet.privateKey);
+  const publicClient = createPublicClient({ chain: baseSepolia, transport: http() });
+  const signer = toClientEvmSigner(account, publicClient);
+  const client = new x402Client();
+  client.register("eip155:84532", new ExactEvmScheme(signer));
+  const fetchPaid = wrapFetchWithPayment(fetch, client);
+
+  const body = { version_id: versionId, name };
+  if (opts.subdomain) body.subdomain = opts.subdomain;
+
+  const res = await fetchPaid(`${API}/v1/fork/${opts.tier}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+
+  // Save project credentials locally
+  if (data.project_id) {
+    const projects = loadProjects();
+    projects.push({
+      project_id: data.project_id, anon_key: data.anon_key, service_key: data.service_key,
+      tier: data.tier, lease_expires_at: data.lease_expires_at,
+      site_url: data.site_url || data.subdomain_url, deployed_at: new Date().toISOString(),
+    });
+    const dir = PROJECTS_FILE.replace(/\/[^/]+$/, "");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(PROJECTS_FILE, JSON.stringify(projects, null, 2), { mode: 0o600 });
+  }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function publish(projectId, args) {
+  const p = findProject(projectId);
+  const opts = { description: undefined, tags: undefined, visibility: undefined, forkAllowed: undefined };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--description" && args[i + 1]) opts.description = args[++i];
+    if (args[i] === "--tags" && args[i + 1]) opts.tags = args[++i].split(",");
+    if (args[i] === "--visibility" && args[i + 1]) opts.visibility = args[++i];
+    if (args[i] === "--fork-allowed") opts.forkAllowed = true;
+  }
+  const body = {};
+  if (opts.description) body.description = opts.description;
+  if (opts.tags) body.tags = opts.tags;
+  if (opts.visibility) body.visibility = opts.visibility;
+  if (opts.forkAllowed !== undefined) body.fork_allowed = opts.forkAllowed;
+
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/publish`, {
+    method: "POST",
+    headers: { "Authorization": `Bearer ${p.service_key}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function versions(projectId) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/versions`, {
+    headers: { "Authorization": `Bearer ${p.service_key}` },
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+export async function run(sub, args) {
+  if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  switch (sub) {
+    case "browse":   await browse(args); break;
+    case "fork":     await fork(args[0], args[1], args.slice(2)); break;
+    case "publish":  await publish(args[0], args.slice(1)); break;
+    case "versions": await versions(args[0]); break;
+    default:
+      console.error(`Unknown subcommand: ${sub}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}

package/lib/functions.mjs

@@ -0,0 +1,150 @@
+import { readFileSync, existsSync } from "fs";
+import { findProject, readWallet, API, WALLET_FILE } from "./config.mjs";
+
+const HELP = `run402 functions — Manage serverless functions
+
+Usage:
+  run402 functions <subcommand> [args...]
+
+Subcommands:
+  deploy <id> <name> --code <file> [--timeout <s>] [--memory <mb>] [--deps <pkg,...>]
+                                       Deploy a function to a project
+  invoke <id> <name> [--method <M>] [--body <json>]
+                                       Invoke a deployed function
+  logs   <id> <name> [--tail <n>]      Get function logs
+  list   <id>                          List all functions for a project
+  delete <id> <name>                   Delete a function
+
+Examples:
+  run402 functions deploy abc123 stripe-webhook --code handler.ts
+  run402 functions invoke abc123 stripe-webhook --body '{"event":"test"}'
+  run402 functions logs abc123 stripe-webhook --tail 100
+  run402 functions list abc123
+  run402 functions delete abc123 stripe-webhook
+
+Notes:
+  - Code must export a default async function: export default async (req: Request) => Response
+  - Deploy may require payment if the project lease has expired
+`;
+
+async function setupPaidFetch() {
+  if (!existsSync(WALLET_FILE)) {
+    console.error(JSON.stringify({ status: "error", message: "No wallet found. Run: run402 wallet create && run402 wallet fund" }));
+    process.exit(1);
+  }
+  const wallet = readWallet();
+  const { privateKeyToAccount } = await import("viem/accounts");
+  const { createPublicClient, http } = await import("viem");
+  const { baseSepolia } = await import("viem/chains");
+  const { x402Client, wrapFetchWithPayment } = await import("@x402/fetch");
+  const { ExactEvmScheme } = await import("@x402/evm/exact/client");
+  const { toClientEvmSigner } = await import("@x402/evm");
+  const account = privateKeyToAccount(wallet.privateKey);
+  const publicClient = createPublicClient({ chain: baseSepolia, transport: http() });
+  const signer = toClientEvmSigner(account, publicClient);
+  const client = new x402Client();
+  client.register("eip155:84532", new ExactEvmScheme(signer));
+  return wrapFetchWithPayment(fetch, client);
+}
+
+async function deploy(projectId, name, args) {
+  const p = findProject(projectId);
+  const opts = { code: null, timeout: undefined, memory: undefined, deps: undefined };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--code" && args[i + 1]) opts.code = args[++i];
+    if (args[i] === "--timeout" && args[i + 1]) opts.timeout = parseInt(args[++i]);
+    if (args[i] === "--memory" && args[i + 1]) opts.memory = parseInt(args[++i]);
+    if (args[i] === "--deps" && args[i + 1]) opts.deps = args[++i].split(",");
+  }
+  if (!opts.code) { console.error(JSON.stringify({ status: "error", message: "Missing --code <file>" })); process.exit(1); }
+  const code = readFileSync(opts.code, "utf-8");
+  const body = { name, code };
+  if (opts.timeout || opts.memory) body.config = {};
+  if (opts.timeout) body.config.timeout = opts.timeout;
+  if (opts.memory) body.config.memory = opts.memory;
+  if (opts.deps) body.deps = opts.deps;
+
+  const fetchPaid = await setupPaidFetch();
+  const res = await fetchPaid(`${API}/admin/v1/projects/${projectId}/functions`, {
+    method: "POST",
+    headers: { "Authorization": `Bearer ${p.service_key}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function invoke(projectId, name, args) {
+  const p = findProject(projectId);
+  const opts = { method: "POST", body: undefined };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--method" && args[i + 1]) opts.method = args[++i];
+    if (args[i] === "--body" && args[i + 1]) opts.body = args[++i];
+  }
+  const fetchOpts = {
+    method: opts.method,
+    headers: { "apikey": p.service_key },
+  };
+  if (opts.body && opts.method !== "GET" && opts.method !== "HEAD") {
+    fetchOpts.headers["Content-Type"] = "application/json";
+    fetchOpts.body = opts.body;
+  }
+  const res = await fetch(`${API}/functions/v1/${name}`, fetchOpts);
+  const text = await res.text();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, body: text })); process.exit(1); }
+  try { console.log(JSON.stringify(JSON.parse(text), null, 2)); } catch { process.stdout.write(text + "\n"); }
+}
+
+async function logs(projectId, name, args) {
+  const p = findProject(projectId);
+  let tail = 50;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--tail" && args[i + 1]) tail = parseInt(args[++i]);
+  }
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/functions/${encodeURIComponent(name)}/logs?tail=${tail}`, {
+    headers: { "Authorization": `Bearer ${p.service_key}` },
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function list(projectId) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/functions`, {
+    headers: { "Authorization": `Bearer ${p.service_key}` },
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function deleteFunction(projectId, name) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/functions/${encodeURIComponent(name)}`, {
+    method: "DELETE",
+    headers: { "Authorization": `Bearer ${p.service_key}` },
+  });
+  if (res.status === 204 || res.ok) {
+    console.log(JSON.stringify({ status: "ok", message: `Function '${name}' deleted.` }));
+  } else {
+    const data = await res.json().catch(() => ({}));
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1);
+  }
+}
+
+export async function run(sub, args) {
+  if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  switch (sub) {
+    case "deploy": await deploy(args[0], args[1], args.slice(2)); break;
+    case "invoke": await invoke(args[0], args[1], args.slice(2)); break;
+    case "logs":   await logs(args[0], args[1], args.slice(2)); break;
+    case "list":   await list(args[0]); break;
+    case "delete": await deleteFunction(args[0], args[1]); break;
+    default:
+      console.error(`Unknown subcommand: ${sub}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}

package/lib/projects.mjs

@@ -1,5 +1,5 @@
-import { findProject, loadProjects, saveProjects, readWallet, API, WALLET_FILE } from "./config.mjs";
-import { existsSync } from "fs";
+import { findProject, loadProjects, saveProjects, readWallet, API, WALLET_FILE, PROJECTS_FILE } from "./config.mjs";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
 
 const HELP = `run402 projects — Manage your deployed Run402 projects
 
@@ -7,27 +7,35 @@ Usage:
   run402 projects <subcommand> [args...]
 
 Subcommands:
-  list                           List all your projects (IDs, tiers, URLs, expiry)
-  sql   <id> "<query>"           Run a SQL query against a project's Postgres DB
-  rest  <id> <table> [params]    Query a table via the REST API (PostgREST)
-  usage <id>                     Show compute/storage usage for a project
-  schema <id>                    Inspect the database schema
-  renew <id>                     Extend the project lease (pays via x402)
-  delete <id>                    Delete a project and remove it from local state
+  quote                                   Show pricing tiers
+  provision [--tier <tier>] [--name <n>]  Provision a new Postgres project (pays via x402)
+  list                                    List all your projects (IDs, tiers, URLs, expiry)
+  sql   <id> "<query>"                    Run a SQL query against a project's Postgres DB
+  rest  <id> <table> [params]             Query a table via the REST API (PostgREST)
+  usage <id>                              Show compute/storage usage for a project
+  schema <id>                             Inspect the database schema
+  rls   <id> <template> <tables_json>     Apply Row-Level Security policies
+  renew <id>                              Extend the project lease (pays via x402)
+  delete <id>                             Delete a project and remove it from local state
 
 Examples:
+  run402 projects quote
+  run402 projects provision --tier prototype
+  run402 projects provision --tier hobby --name my-app
   run402 projects list
   run402 projects sql abc123 "SELECT * FROM users LIMIT 5"
   run402 projects rest abc123 users "limit=10&select=id,name"
   run402 projects usage abc123
   run402 projects schema abc123
+  run402 projects rls abc123 public_read '[{"table":"posts"}]'
   run402 projects renew abc123
   run402 projects delete abc123
 
 Notes:
   - <id> is the project_id shown in 'run402 projects list'
   - 'rest' uses PostgREST query syntax (table name + optional query string)
-  - 'renew' requires a funded wallet — payment is automatic via x402
+  - 'renew' and 'provision' require a funded wallet — payment is automatic via x402
+  - RLS templates: user_owns_rows, public_read, public_read_write
 `;
 
 async function setupPaidFetch() {
@@ -50,6 +58,56 @@ async function setupPaidFetch() {
   return wrapFetchWithPayment(fetch, client);
 }
 
+async function quote() {
+  const res = await fetch(`${API}/v1/projects`);
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function provision(args) {
+  const opts = { tier: "prototype", name: undefined };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--tier" && args[i + 1]) opts.tier = args[++i];
+    if (args[i] === "--name" && args[i + 1]) opts.name = args[++i];
+  }
+  const fetchPaid = await setupPaidFetch();
+  const body = { tier: opts.tier };
+  if (opts.name) body.name = opts.name;
+  const res = await fetchPaid(`${API}/v1/projects`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  // Save project credentials locally
+  if (data.project_id) {
+    const projects = loadProjects();
+    projects.push({
+      project_id: data.project_id, anon_key: data.anon_key, service_key: data.service_key,
+      tier: data.tier, lease_expires_at: data.lease_expires_at, deployed_at: new Date().toISOString(),
+    });
+    const dir = PROJECTS_FILE.replace(/\/[^/]+$/, "");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(PROJECTS_FILE, JSON.stringify(projects, null, 2), { mode: 0o600 });
+  }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function rls(projectId, template, tablesJson) {
+  const p = findProject(projectId);
+  const tables = JSON.parse(tablesJson);
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/rls`, {
+    method: "POST",
+    headers: { "Authorization": `Bearer ${p.service_key}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ template, tables }),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
 async function list() {
   const projects = loadProjects();
   if (projects.length === 0) { console.log(JSON.stringify({ status: "ok", projects: [], message: "No projects yet." })); return; }
@@ -113,13 +171,16 @@ export async function run(sub, args) {
     process.exit(0);
   }
   switch (sub) {
-    case "list":   await list(); break;
-    case "sql":    await sqlCmd(args[0], args[1]); break;
-    case "rest":   await rest(args[0], args[1], args[2]); break;
-    case "usage":  await usage(args[0]); break;
-    case "schema": await schema(args[0]); break;
-    case "renew":  await renew(args[0]); break;
-    case "delete": await deleteProject(args[0]); break;
+    case "quote":     await quote(); break;
+    case "provision": await provision(args); break;
+    case "list":      await list(); break;
+    case "sql":       await sqlCmd(args[0], args[1]); break;
+    case "rest":      await rest(args[0], args[1], args[2]); break;
+    case "usage":     await usage(args[0]); break;
+    case "schema":    await schema(args[0]); break;
+    case "rls":       await rls(args[0], args[1], args[2]); break;
+    case "renew":     await renew(args[0]); break;
+    case "delete":    await deleteProject(args[0]); break;
     default:
       console.error(`Unknown subcommand: ${sub}\n`);
       console.log(HELP);

package/lib/secrets.mjs

@@ -0,0 +1,70 @@
+import { findProject, API } from "./config.mjs";
+
+const HELP = `run402 secrets — Manage project secrets
+
+Usage:
+  run402 secrets <subcommand> [args...]
+
+Subcommands:
+  set    <id> <key> <value>    Set a secret on a project
+  list   <id>                  List all secrets for a project
+  delete <id> <key>            Delete a secret from a project
+
+Examples:
+  run402 secrets set abc123 STRIPE_KEY sk-1234
+  run402 secrets list abc123
+  run402 secrets delete abc123 STRIPE_KEY
+
+Notes:
+  - Secrets are injected as process.env in serverless functions
+  - Values are never shown after being set
+`;
+
+async function set(projectId, key, value) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/secrets`, {
+    method: "POST",
+    headers: { "Authorization": `Bearer ${p.service_key}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ key, value }),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify({ status: "ok", message: `Secret '${key}' set for project ${projectId}.` }));
+}
+
+async function list(projectId) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/secrets`, {
+    headers: { "Authorization": `Bearer ${p.service_key}` },
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function deleteSecret(projectId, key) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/secrets/${encodeURIComponent(key)}`, {
+    method: "DELETE",
+    headers: { "Authorization": `Bearer ${p.service_key}` },
+  });
+  if (res.status === 204 || res.ok) {
+    console.log(JSON.stringify({ status: "ok", message: `Secret '${key}' deleted.` }));
+  } else {
+    const data = await res.json().catch(() => ({}));
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1);
+  }
+}
+
+export async function run(sub, args) {
+  if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  switch (sub) {
+    case "set":    await set(args[0], args[1], args[2]); break;
+    case "list":   await list(args[0]); break;
+    case "delete": await deleteSecret(args[0], args[1]); break;
+    default:
+      console.error(`Unknown subcommand: ${sub}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}

package/lib/sites.mjs

@@ -0,0 +1,92 @@
+import { readFileSync, existsSync } from "fs";
+import { readWallet, API, WALLET_FILE } from "./config.mjs";
+
+const HELP = `run402 sites — Deploy static sites
+
+Usage:
+  run402 sites deploy --name <name> --manifest <file> [--project <id>] [--target <target>]
+  cat manifest.json | run402 sites deploy --name <name>
+
+Options:
+  --name <name>         Site name (e.g. 'portfolio', 'family-todo')
+  --manifest <file>     Path to manifest JSON file (or read from stdin)
+  --project <id>        Optional project ID to link this deployment to
+  --target <target>     Deployment target (e.g. 'production')
+  --help, -h            Show this help message
+
+Manifest format (JSON):
+  {
+    "files": [
+      { "file": "index.html", "data": "<html>...</html>" },
+      { "file": "style.css", "data": "body { margin: 0; }" }
+    ]
+  }
+
+Examples:
+  run402 sites deploy --name my-site --manifest site.json
+  cat site.json | run402 sites deploy --name my-site
+
+Notes:
+  - Must include at least index.html in the files array
+  - Requires a funded wallet — payment ($0.05 USDC) is automatic via x402
+`;
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+async function deploy(args) {
+  const opts = { name: null, manifest: null, project: undefined, target: undefined };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--help" || args[i] === "-h") { console.log(HELP); process.exit(0); }
+    if (args[i] === "--name" && args[i + 1]) opts.name = args[++i];
+    if (args[i] === "--manifest" && args[i + 1]) opts.manifest = args[++i];
+    if (args[i] === "--project" && args[i + 1]) opts.project = args[++i];
+    if (args[i] === "--target" && args[i + 1]) opts.target = args[++i];
+  }
+  if (!opts.name) { console.error(JSON.stringify({ status: "error", message: "Missing --name <name>" })); process.exit(1); }
+  if (!existsSync(WALLET_FILE)) {
+    console.error(JSON.stringify({ status: "error", message: "No wallet found. Run: run402 wallet create && run402 wallet fund" }));
+    process.exit(1);
+  }
+
+  const manifest = opts.manifest ? JSON.parse(readFileSync(opts.manifest, "utf-8")) : JSON.parse(await readStdin());
+  const body = { name: opts.name, files: manifest.files };
+  if (opts.project) body.project = opts.project;
+  if (opts.target) body.target = opts.target;
+
+  const wallet = readWallet();
+  const { privateKeyToAccount } = await import("viem/accounts");
+  const { createPublicClient, http } = await import("viem");
+  const { baseSepolia } = await import("viem/chains");
+  const { x402Client, wrapFetchWithPayment } = await import("@x402/fetch");
+  const { ExactEvmScheme } = await import("@x402/evm/exact/client");
+  const { toClientEvmSigner } = await import("@x402/evm");
+  const account = privateKeyToAccount(wallet.privateKey);
+  const publicClient = createPublicClient({ chain: baseSepolia, transport: http() });
+  const signer = toClientEvmSigner(account, publicClient);
+  const client = new x402Client();
+  client.register("eip155:84532", new ExactEvmScheme(signer));
+  const fetchPaid = wrapFetchWithPayment(fetch, client);
+
+  const res = await fetchPaid(`${API}/v1/deployments`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+export async function run(sub, args) {
+  if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  if (sub !== "deploy") {
+    console.error(`Unknown subcommand: ${sub}\n`);
+    console.log(HELP);
+    process.exit(1);
+  }
+  await deploy(args);
+}

package/lib/storage.mjs

@@ -0,0 +1,101 @@
+import { readFileSync } from "fs";
+import { findProject, API } from "./config.mjs";
+
+const HELP = `run402 storage — Manage project file storage
+
+Usage:
+  run402 storage <subcommand> [args...]
+
+Subcommands:
+  upload   <id> <bucket> <path> [--file <local>] [--content-type <mime>]
+                                       Upload a file to storage
+  download <id> <bucket> <path>        Download a file from storage
+  delete   <id> <bucket> <path>        Delete a file from storage
+  list     <id> <bucket>               List files in a bucket
+
+Examples:
+  run402 storage upload abc123 assets logo.png --file ./logo.png --content-type image/png
+  echo "hello" | run402 storage upload abc123 data notes.txt
+  run402 storage download abc123 assets logo.png
+  run402 storage list abc123 assets
+  run402 storage delete abc123 assets logo.png
+
+Notes:
+  - <id> is the project_id from 'run402 projects list'
+  - Upload reads from --file or stdin if no --file is given
+`;
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+async function upload(projectId, bucket, path, args) {
+  const p = findProject(projectId);
+  const opts = { file: null, contentType: "text/plain" };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--file" && args[i + 1]) opts.file = args[++i];
+    if (args[i] === "--content-type" && args[i + 1]) opts.contentType = args[++i];
+  }
+  const content = opts.file ? readFileSync(opts.file, "utf-8") : await readStdin();
+  const res = await fetch(`${API}/storage/v1/object/${bucket}/${path}`, {
+    method: "POST",
+    headers: { "Content-Type": opts.contentType, "apikey": p.anon_key, "Authorization": `Bearer ${p.anon_key}` },
+    body: content,
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function download(projectId, bucket, path) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/storage/v1/object/${bucket}/${path}`, {
+    headers: { "apikey": p.anon_key, "Authorization": `Bearer ${p.anon_key}` },
+  });
+  if (!res.ok) {
+    const data = await res.json().catch(() => ({}));
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1);
+  }
+  const text = await res.text();
+  process.stdout.write(text);
+}
+
+async function deleteFile(projectId, bucket, path) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/storage/v1/object/${bucket}/${path}`, {
+    method: "DELETE",
+    headers: { "apikey": p.anon_key, "Authorization": `Bearer ${p.anon_key}` },
+  });
+  if (res.status === 204 || res.ok) {
+    console.log(JSON.stringify({ status: "ok", message: `File '${bucket}/${path}' deleted.` }));
+  } else {
+    const data = await res.json().catch(() => ({}));
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1);
+  }
+}
+
+async function list(projectId, bucket) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/storage/v1/object/list/${bucket}`, {
+    headers: { "apikey": p.anon_key, "Authorization": `Bearer ${p.anon_key}` },
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+export async function run(sub, args) {
+  if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  switch (sub) {
+    case "upload":   await upload(args[0], args[1], args[2], args.slice(3)); break;
+    case "download": await download(args[0], args[1], args[2]); break;
+    case "delete":   await deleteFile(args[0], args[1], args[2]); break;
+    case "list":     await list(args[0], args[1]); break;
+    default:
+      console.error(`Unknown subcommand: ${sub}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}

package/lib/subdomains.mjs

@@ -0,0 +1,87 @@
+import { findProject, API } from "./config.mjs";
+
+const HELP = `run402 subdomains — Manage custom subdomains
+
+Usage:
+  run402 subdomains <subcommand> [args...]
+
+Subcommands:
+  claim  <deployment_id> <name> [--project <id>]   Claim a subdomain for a deployment
+  delete <name> [--project <id>]                    Release a subdomain
+  list   <id>                                       List subdomains for a project
+
+Examples:
+  run402 subdomains claim dpl_abc123 myapp
+  run402 subdomains claim dpl_abc123 myapp --project proj123
+  run402 subdomains delete myapp
+  run402 subdomains list proj123
+
+Notes:
+  - Subdomain names: 3-63 chars, lowercase alphanumeric + hyphens
+  - Creates <name>.run402.com pointing to the deployment
+`;
+
+async function claim(deploymentId, name, args) {
+  const opts = { project: null };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--project" && args[i + 1]) opts.project = args[++i];
+  }
+  const headers = { "Content-Type": "application/json" };
+  if (opts.project) {
+    const p = findProject(opts.project);
+    headers["Authorization"] = `Bearer ${p.service_key}`;
+  }
+  const res = await fetch(`${API}/v1/subdomains`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ name, deployment_id: deploymentId }),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function deleteSubdomain(name, args) {
+  const opts = { project: null };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--project" && args[i + 1]) opts.project = args[++i];
+  }
+  const headers = {};
+  if (opts.project) {
+    const p = findProject(opts.project);
+    headers["Authorization"] = `Bearer ${p.service_key}`;
+  }
+  const res = await fetch(`${API}/v1/subdomains/${encodeURIComponent(name)}`, {
+    method: "DELETE",
+    headers,
+  });
+  if (res.status === 204 || res.ok) {
+    console.log(JSON.stringify({ status: "ok", message: `Subdomain '${name}' released.` }));
+  } else {
+    const data = await res.json().catch(() => ({}));
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1);
+  }
+}
+
+async function list(projectId) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/v1/subdomains`, {
+    headers: { "Authorization": `Bearer ${p.service_key}` },
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+export async function run(sub, args) {
+  if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  switch (sub) {
+    case "claim":  await claim(args[0], args[1], args.slice(2)); break;
+    case "delete": await deleteSubdomain(args[0], args.slice(1)); break;
+    case "list":   await list(args[0]); break;
+    default:
+      console.error(`Unknown subcommand: ${sub}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}

package/lib/wallet.mjs

@@ -9,6 +9,7 @@ Subcommands:
   status    Show wallet address, network, and funding status
   create    Generate a new wallet and save it locally
   fund      Request test USDC from the Run402 faucet (Base Sepolia)
+  balance   Check billing balance for this wallet
   export    Print the wallet address (useful for scripting)
 
 Notes:
@@ -65,6 +66,15 @@ async function fund() {
   }
 }
 
+async function balance() {
+  const w = readWallet();
+  if (!w) { console.log(JSON.stringify({ status: "error", message: "No wallet. Run: run402 wallet create" })); process.exit(1); }
+  const res = await fetch(`${API}/v1/billing/accounts/${w.address.toLowerCase()}`);
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
 async function exportAddr() {
   const w = readWallet();
   if (!w) { console.log(JSON.stringify({ status: "error", message: "No wallet." })); process.exit(1); }
@@ -77,10 +87,11 @@ export async function run(sub, args) {
     process.exit(0);
   }
   switch (sub) {
-    case "status": await status(); break;
-    case "create": await create(); break;
-    case "fund":   await fund(); break;
-    case "export": await exportAddr(); break;
+    case "status":  await status(); break;
+    case "create":  await create(); break;
+    case "fund":    await fund(); break;
+    case "balance": await balance(); break;
+    case "export":  await exportAddr(); break;
     default:
       console.error(`Unknown subcommand: ${sub}\n`);
       console.log(HELP);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 micropayments.",
   "type": "module",
   "bin": {