@lark-sh/cli 0.1.0

package/dist/index.js

@@ -0,0 +1,1063 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/auth/login.ts
+import http from "http";
+import open from "open";
+
+// src/config.ts
+import fs from "fs";
+import path from "path";
+import os from "os";
+var CONFIG_DIR = path.join(os.homedir(), ".lark");
+var CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+function ensureDir() {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { mode: 448, recursive: true });
+  }
+}
+function readConfig() {
+  try {
+    const data = fs.readFileSync(CONFIG_FILE, "utf-8");
+    return JSON.parse(data);
+  } catch {
+    return {};
+  }
+}
+function writeConfig(config) {
+  ensureDir();
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n", {
+    mode: 384
+  });
+}
+function getSession() {
+  return readConfig().session;
+}
+function setSession(session) {
+  const config = readConfig();
+  config.session = session;
+  writeConfig(config);
+}
+function clearSession() {
+  const config = readConfig();
+  delete config.session;
+  delete config.adminTokens;
+  writeConfig(config);
+}
+function getDefaultProject() {
+  return readConfig().defaultProject;
+}
+function setDefaultProject(projectId) {
+  const config = readConfig();
+  config.defaultProject = projectId;
+  writeConfig(config);
+}
+function getCachedAdminToken(projectId) {
+  const config = readConfig();
+  const entry = config.adminTokens?.[projectId];
+  if (!entry) return void 0;
+  if (entry.expiresAt > Date.now() + 5 * 60 * 1e3) {
+    return entry.token;
+  }
+  return void 0;
+}
+function setCachedAdminToken(projectId, token, expiresAt) {
+  const config = readConfig();
+  if (!config.adminTokens) config.adminTokens = {};
+  config.adminTokens[projectId] = { token, expiresAt };
+  writeConfig(config);
+}
+
+// src/utils.ts
+var ApiError = class extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+  }
+};
+function resolveProject(explicit) {
+  const projectId = explicit || getDefaultProject();
+  if (!projectId) {
+    error(
+      "No project specified. Use --project <id> or run: lark config set-project <id>"
+    );
+  }
+  return projectId;
+}
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    process.stdin.on("data", (chunk) => chunks.push(chunk));
+    process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    process.stdin.on("error", reject);
+  });
+}
+function error(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+function jsonError(message, status) {
+  console.log(JSON.stringify({ error: message, ...status ? { status } : {} }));
+  process.exit(1);
+}
+function handleError(err, json) {
+  if (err instanceof ApiError) {
+    if (json) {
+      jsonError(err.message, err.status);
+    }
+    if (err.status === 401) {
+      error("Not authenticated. Run: lark login");
+    }
+    error(err.message);
+  }
+  const msg = err instanceof Error ? err.message : String(err);
+  if (json) {
+    jsonError(msg);
+  }
+  error(msg);
+}
+
+// src/api/admin.ts
+var API_BASE = "https://db.lark.sh";
+async function adminRequest(method, path2, body) {
+  const session = getSession();
+  if (!session) {
+    throw new ApiError(401, "Not authenticated. Run: lark login");
+  }
+  const headers = {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    Cookie: `lark_session=${session}`
+  };
+  const res = await fetch(`${API_BASE}${path2}`, {
+    method,
+    headers,
+    body: body !== void 0 ? JSON.stringify(body) : void 0
+  });
+  if (!res.ok) {
+    let message = "Request failed";
+    try {
+      const err = await res.json();
+      message = err.error || err.message || message;
+    } catch {
+    }
+    throw new ApiError(res.status, message);
+  }
+  return res.json();
+}
+var admin = {
+  getMe: () => adminRequest("GET", "/me"),
+  logout: () => adminRequest("POST", "/auth/logout"),
+  getProjects: () => adminRequest("GET", "/projects"),
+  createProject: (name) => adminRequest("POST", "/projects", { name }),
+  getProject: (id) => adminRequest("GET", `/projects/${id}`),
+  updateProject: (id, updates) => adminRequest("PATCH", `/projects/${id}`, updates),
+  deleteProject: (id, confirm) => adminRequest("DELETE", `/projects/${id}`, { confirm }),
+  regenerateSecret: (id) => adminRequest("POST", `/projects/${id}/regenerate-secret`),
+  getAdminToken: (projectId, database) => adminRequest("POST", `/projects/${projectId}/admin-token`, database ? { database } : {}),
+  getDatabases: (projectId, opts) => {
+    const params = new URLSearchParams();
+    if (opts?.limit) params.set("limit", String(opts.limit));
+    if (opts?.offset) params.set("offset", String(opts.offset));
+    if (opts?.search) params.set("search", opts.search);
+    const q = params.toString();
+    return adminRequest(
+      "GET",
+      `/projects/${projectId}/databases${q ? `?${q}` : ""}`
+    );
+  },
+  createDatabase: (projectId, id) => adminRequest("POST", `/projects/${projectId}/databases`, { id }),
+  deleteDatabase: (projectId, dbId) => adminRequest("DELETE", `/projects/${projectId}/databases/${dbId}`),
+  getDashboard: (projectId, opts) => {
+    const params = new URLSearchParams();
+    if (opts?.start) params.set("start", opts.start);
+    if (opts?.end) params.set("end", opts.end);
+    const q = params.toString();
+    return adminRequest("GET", `/projects/${projectId}/dashboard${q ? `?${q}` : ""}`);
+  },
+  getEvents: (projectId, opts) => {
+    const params = new URLSearchParams();
+    if (opts?.limit) params.set("limit", String(opts.limit));
+    if (opts?.offset) params.set("offset", String(opts.offset));
+    const q = params.toString();
+    return adminRequest(
+      "GET",
+      `/projects/${projectId}/events${q ? `?${q}` : ""}`
+    );
+  },
+  getBilling: (projectId, period) => {
+    const params = new URLSearchParams();
+    if (period) params.set("period", period);
+    const q = params.toString();
+    return adminRequest("GET", `/projects/${projectId}/billing${q ? `?${q}` : ""}`);
+  }
+};
+
+// src/auth/login.ts
+var DASHBOARD_URL = "https://dashboard.lark.sh";
+async function login() {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url, `http://localhost`);
+      if (url.pathname !== "/callback") {
+        res.writeHead(404);
+        res.end("Not found");
+        return;
+      }
+      const token = url.searchParams.get("token");
+      if (!token) {
+        res.writeHead(400);
+        res.end("Missing token");
+        reject(new Error("Authorization callback missing token"));
+        server.close();
+        return;
+      }
+      setSession(token);
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end(`
+        <!DOCTYPE html>
+        <html>
+        <head><title>Lark CLI</title></head>
+        <body style="font-family: system-ui; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background-color: #364f6b; color: white;">
+          <div style="text-align: center;">
+            <h1>CLI Authorized!</h1>
+            <p>You can close this window and return to the terminal.</p>
+          </div>
+        </body>
+        </html>
+      `);
+      admin.getMe().then((user) => {
+        resolve({ name: user.name, email: user.email });
+      }).catch((err) => {
+        reject(err);
+      }).finally(() => {
+        server.close();
+      });
+    });
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (!addr || typeof addr === "string") {
+        reject(new Error("Failed to start local server"));
+        return;
+      }
+      const port = addr.port;
+      const authUrl = `${DASHBOARD_URL}/cli-auth?port=${port}`;
+      console.log("Opening browser to authorize...");
+      open(authUrl).catch(() => {
+        console.log(`
+If the browser didn't open, visit:
+${authUrl}
+`);
+      });
+    });
+    server.on("error", reject);
+    const timeout = setTimeout(() => {
+      server.close();
+      reject(new Error("Login timed out after 5 minutes"));
+    }, 5 * 60 * 1e3);
+    timeout.unref();
+  });
+}
+
+// src/commands/auth.ts
+function registerAuthCommands(program2) {
+  program2.command("login").description(
+    "Log in to Lark via your browser.\n\nOpens the Lark dashboard where you authorize the CLI.\nYour session is saved to ~/.lark/config.json.\n\nExample:\n  $ lark login"
+  ).action(async () => {
+    try {
+      const { name, email } = await login();
+      console.log(`Logged in as ${name} (${email})`);
+    } catch (err) {
+      handleError(err, false);
+    }
+  });
+  program2.command("logout").description(
+    "Log out and clear the stored session.\n\nExample:\n  $ lark logout"
+  ).action(async () => {
+    const json = program2.opts().json;
+    try {
+      const session = getSession();
+      if (session) {
+        try {
+          await admin.logout();
+        } catch {
+        }
+      }
+      clearSession();
+      if (json) {
+        console.log(JSON.stringify({ success: true }));
+      } else {
+        console.log("Logged out.");
+      }
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+  program2.command("whoami").description(
+    "Show the currently logged-in user.\n\nExamples:\n  $ lark whoami\n  $ lark whoami --json"
+  ).action(async () => {
+    const json = program2.opts().json;
+    try {
+      const user = await admin.getMe();
+      if (json) {
+        console.log(JSON.stringify(user, null, 2));
+      } else {
+        console.log(`${user.name} (${user.email})`);
+      }
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+}
+
+// src/commands/config.ts
+function registerConfigCommands(program2) {
+  const config = program2.command("config").description(
+    "Manage CLI configuration.\n\nSettings are stored in ~/.lark/config.json."
+  );
+  config.command("set-project <id>").description(
+    "Set the default project for all commands.\n\nOnce set, you can omit --project from other commands.\nThe project ID is verified before saving.\n\nExamples:\n  $ lark config set-project my-app\n  $ lark config set-project cli-test"
+  ).action(async (id) => {
+    const json = program2.opts().json;
+    try {
+      const project = await admin.getProject(id);
+      setDefaultProject(id);
+      if (json) {
+        console.log(JSON.stringify({ defaultProject: id, name: project.name }));
+      } else {
+        console.log(`Default project set to: ${project.name} (${id})`);
+      }
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+  config.command("show").description(
+    "Show current CLI configuration.\n\nExample:\n  $ lark config show"
+  ).action(() => {
+    const json = program2.opts().json;
+    const defaultProject = getDefaultProject();
+    if (json) {
+      console.log(JSON.stringify({ defaultProject: defaultProject || null }));
+    } else {
+      console.log(`Default project: ${defaultProject || "(not set)"}`);
+    }
+  });
+}
+
+// src/output.ts
+function table(rows, columns) {
+  if (rows.length === 0) {
+    console.log("(none)");
+    return;
+  }
+  const cols = columns || Object.keys(rows[0]);
+  const widths = cols.map((col) => col.length);
+  const formatted = rows.map(
+    (row) => cols.map((col, i) => {
+      const val = formatValue(row[col]);
+      widths[i] = Math.max(widths[i], val.length);
+      return val;
+    })
+  );
+  console.log(cols.map((col, i) => col.toUpperCase().padEnd(widths[i])).join("  "));
+  console.log(widths.map((w) => "-".repeat(w)).join("  "));
+  for (const row of formatted) {
+    console.log(row.map((val, i) => val.padEnd(widths[i])).join("  "));
+  }
+}
+function keyValue(pairs) {
+  const maxKey = Math.max(...Object.keys(pairs).map((k) => k.length));
+  for (const [key, value] of Object.entries(pairs)) {
+    console.log(`${key.padEnd(maxKey)}  ${formatValue(value)}`);
+  }
+}
+function formatValue(val) {
+  if (val === null || val === void 0) return "-";
+  if (typeof val === "boolean") return val ? "yes" : "no";
+  if (typeof val === "number") return String(val);
+  return String(val);
+}
+function formatBytes(bytes) {
+  if (bytes === 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  const val = bytes / Math.pow(1024, i);
+  return `${val.toFixed(i === 0 ? 0 : 1)} ${units[i]}`;
+}
+function formatLatency(us) {
+  if (us < 1e3) return `${us.toFixed(0)}\xB5s`;
+  if (us < 1e6) return `${(us / 1e3).toFixed(1)}ms`;
+  return `${(us / 1e6).toFixed(2)}s`;
+}
+function formatTime(ts) {
+  const d = typeof ts === "number" ? new Date(ts) : new Date(ts);
+  return d.toLocaleString();
+}
+
+// src/commands/projects.ts
+function registerProjectCommands(program2) {
+  const projects = program2.command("projects").description(
+    'Manage Lark projects.\n\nA project is the top-level container for databases, rules, and settings.\nEach project gets a unique ID (DNS-compatible slug) and a secret key.\n\nExamples:\n  $ lark projects list\n  $ lark projects create "My App"\n  $ lark projects show my-app'
+  );
+  projects.command("list").description(
+    "List all your projects.\n\nExamples:\n  $ lark projects list\n  $ lark projects list --json"
+  ).action(async () => {
+    const json = program2.opts().json;
+    try {
+      const { projects: list } = await admin.getProjects();
+      if (json) {
+        console.log(JSON.stringify(list, null, 2));
+        return;
+      }
+      table(
+        list.map((p) => ({
+          id: p.id,
+          name: p.name,
+          databases: p.database_count,
+          created: formatTime(p.created_at)
+        }))
+      );
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+  projects.command("create <name>").description(
+    'Create a new project.\n\nThe name is used to generate a DNS-compatible project ID.\nFor example, "My App" becomes "my-app".\n\nExamples:\n  $ lark projects create "My App"\n  $ lark projects create "Game Server" --json'
+  ).action(async (name) => {
+    const json = program2.opts().json;
+    try {
+      const project = await admin.createProject(name);
+      if (json) {
+        console.log(JSON.stringify(project, null, 2));
+        return;
+      }
+      console.log(`Created project: ${project.name} (${project.id})`);
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+  projects.command("show [id]").description(
+    "Show project details including secret key and settings.\n\nUses the default project if no ID is given.\n\nExamples:\n  $ lark projects show\n  $ lark projects show my-app\n  $ lark projects show --json"
+  ).action(async (id) => {
+    const json = program2.opts().json;
+    try {
+      const projectId = resolveProject(id || program2.opts().project);
+      const project = await admin.getProject(projectId);
+      if (json) {
+        console.log(JSON.stringify(project, null, 2));
+        return;
+      }
+      keyValue({
+        "ID": project.id,
+        "Name": project.name,
+        "Secret Key": project.secret_key,
+        "Ephemeral": project.ephemeral,
+        "Auto Create": project.auto_create,
+        "Firebase Compat": project.firebase_compat_enabled,
+        "Databases": project.database_count ?? 0,
+        "Active DBs": project.active_database_count ?? 0,
+        "Created": formatTime(project.created_at)
+      });
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+  projects.command("update [id]").description(
+    'Update project settings.\n\nPass one or more flags to change settings.\nUses the default project if no ID is given.\n\nExamples:\n  $ lark projects update --name "New Name"\n  $ lark projects update my-app --ephemeral false\n  $ lark projects update --auto-create true --ephemeral true'
+  ).option("--name <name>", "Project name").option("--ephemeral <bool>", "Enable/disable ephemeral mode (true/false)").option("--auto-create <bool>", "Enable/disable auto-create databases (true/false)").option("--firebase-compat <bool>", "Enable/disable Firebase compatibility (true/false)").option("--firebase-project-id <id>", "Firebase project ID").action(async (id, opts) => {
+    const json = program2.opts().json;
+    try {
+      const projectId = resolveProject(id || program2.opts().project);
+      const updates = {};
+      if (opts.name !== void 0) updates.name = opts.name;
+      if (opts.ephemeral !== void 0) updates.ephemeral = opts.ephemeral === "true";
+      if (opts.autoCreate !== void 0) updates.auto_create = opts.autoCreate === "true";
+      if (opts.firebaseCompat !== void 0) updates.firebase_compat_enabled = opts.firebaseCompat === "true";
+      if (opts.firebaseProjectId !== void 0) updates.firebase_project_id = opts.firebaseProjectId;
+      if (Object.keys(updates).length === 0) {
+        if (json) {
+          console.log(JSON.stringify({ error: "No update flags provided" }));
+        } else {
+          console.error("Error: No update flags provided. See --help for options.");
+        }
+        process.exit(1);
+      }
+      const project = await admin.updateProject(projectId, updates);
+      if (json) {
+        console.log(JSON.stringify(project, null, 2));
+        return;
+      }
+      console.log(`Updated project: ${project.name} (${project.id})`);
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+  projects.command("delete [id]").description(
+    "Delete a project and all its databases.\n\nThis is irreversible. You must pass --confirm with the project ID.\n\nExamples:\n  $ lark projects delete my-app --confirm my-app\n  $ lark projects delete --confirm cli-test"
+  ).option("--confirm <id>", "Confirm deletion by passing the project ID").action(async (id, opts) => {
+    const json = program2.opts().json;
+    try {
+      const projectId = resolveProject(id || program2.opts().project);
+      if (!opts.confirm) {
+        if (json) {
+          console.log(JSON.stringify({ error: `Pass --confirm ${projectId} to delete` }));
+        } else {
+          console.error(`Error: Pass --confirm ${projectId} to confirm deletion.`);
+        }
+        process.exit(1);
+      }
+      await admin.deleteProject(projectId, opts.confirm);
+      if (json) {
+        console.log(JSON.stringify({ success: true }));
+      } else {
+        console.log(`Deleted project: ${projectId}`);
+      }
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+  projects.command("regenerate-secret [id]").description(
+    "Regenerate the project secret key.\n\nThe old key is immediately invalidated. Any clients using it\nwill need to be updated.\n\nExamples:\n  $ lark projects regenerate-secret\n  $ lark projects regenerate-secret my-app"
+  ).action(async (id) => {
+    const json = program2.opts().json;
+    try {
+      const projectId = resolveProject(id || program2.opts().project);
+      const result = await admin.regenerateSecret(projectId);
+      if (json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`New secret key: ${result.secret_key}`);
+      }
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+}
+
+// src/commands/databases.ts
+function registerDatabaseCommands(program2) {
+  const databases = program2.command("databases").alias("db").description(
+    'Manage databases within a project.\n\nDatabases hold your real-time data. Use "lark data" commands\nto read and write data within a database.\n\nShorthand: "lark db" works the same as "lark databases".\n\nExamples:\n  $ lark databases list\n  $ lark db create my-database\n  $ lark db list --search "user"'
+  );
+  databases.command("list").description(
+    'List databases in the current project.\n\nExamples:\n  $ lark databases list\n  $ lark databases list --search "chat"\n  $ lark databases list --limit 10 --offset 20\n  $ lark --project my-app databases list'
+  ).option("--search <query>", "Filter databases by ID").option("--limit <n>", "Max results to return", "50").option("--offset <n>", "Number of results to skip", "0").action(async (opts) => {
+    const json = program2.opts().json;
+    try {
+      const projectId = resolveProject(program2.opts().project);
+      const result = await admin.getDatabases(projectId, {
+        search: opts.search,
+        limit: parseInt(opts.limit),
+        offset: parseInt(opts.offset)
+      });
+      if (json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+      console.log(`Total: ${result.total}`);
+      if (result.databases.length === 0) {
+        console.log("(no databases)");
+        return;
+      }
+      table(
+        result.databases.map((db) => ({
+          id: db.id,
+          status: db.status,
+          created: formatTime(db.created_at),
+          "last activity": db.last_activity ? formatTime(db.last_activity) : "-"
+        }))
+      );
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+  databases.command("create <id>").description(
+    "Create a new database.\n\nThe ID must be a valid identifier (lowercase, hyphens allowed).\n\nExamples:\n  $ lark databases create users\n  $ lark databases create game-state\n  $ lark db create chat-rooms --json"
+  ).action(async (id) => {
+    const json = program2.opts().json;
+    try {
+      const projectId = resolveProject(program2.opts().project);
+      const db = await admin.createDatabase(projectId, id);
+      if (json) {
+        console.log(JSON.stringify(db, null, 2));
+      } else {
+        console.log(`Created database: ${db.id}`);
+      }
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+  databases.command("delete <id>").description(
+    "Delete a database and all its data.\n\nThis is irreversible.\n\nExamples:\n  $ lark databases delete old-data\n  $ lark db delete test-db"
+  ).action(async (id) => {
+    const json = program2.opts().json;
+    try {
+      const projectId = resolveProject(program2.opts().project);
+      await admin.deleteDatabase(projectId, id);
+      if (json) {
+        console.log(JSON.stringify({ success: true }));
+      } else {
+        console.log(`Deleted database: ${id}`);
+      }
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+}
+
+// src/commands/data.ts
+import fs2 from "fs";
+
+// src/auth/token.ts
+async function getAdminToken(projectId) {
+  const cached = getCachedAdminToken(projectId);
+  if (cached) return cached;
+  const { token } = await admin.getAdminToken(projectId);
+  const expiresAt = Date.now() + 55 * 60 * 1e3;
+  setCachedAdminToken(projectId, token, expiresAt);
+  return token;
+}
+
+// src/api/data.ts
+async function dataRequest(projectId, method, database, path2, body) {
+  const token = await getAdminToken(projectId);
+  const normalizedPath = path2.startsWith("/") ? path2 : `/${path2}`;
+  const url = `https://${projectId}.larkdb.net/${database}${normalizedPath}.json?v=2&auth=${token}`;
+  const headers = {
+    "Content-Type": "application/json",
+    Accept: "application/json"
+  };
+  const res = await fetch(url, {
+    method,
+    headers,
+    body: body !== void 0 ? typeof body === "string" ? body : JSON.stringify(body) : void 0
+  });
+  if (!res.ok) {
+    let message = "Request failed";
+    try {
+      const err = await res.json();
+      message = err.error || message;
+    } catch {
+      message = await res.text().catch(() => message);
+    }
+    throw new ApiError(res.status, message);
+  }
+  return res.json();
+}
+
+// src/commands/data.ts
+function registerDataCommands(program2) {
+  const data = program2.command("data").description(
+    `Read and write data in your databases.
+
+Data is organized as a JSON tree. Use paths like "/" for the
+root, "/users/alice" for nested data, etc.
+
+Examples:
+  $ lark data get mydb /
+  $ lark data set mydb /users/alice '{"name": "Alice"}'
+  $ lark data watch mydb /messages`
+  );
+  data.command("get <database> <path>").description(
+    'Get data at a path.\n\nReturns the JSON value at the given path. Use "/" to get\nthe entire database.\n\nArguments:\n  database  Database ID (e.g. "users")\n  path      Path in the database (e.g. "/", "/users/alice")\n\nExamples:\n  $ lark data get mydb /\n  $ lark data get mydb /users/alice\n  $ lark data get mydb /settings/theme --json'
+  ).action(async (database, path2) => {
+    const json = program2.opts().json;
+    try {
+      const projectId = resolveProject(program2.opts().project);
+      const result = await dataRequest(projectId, "GET", database, path2);
+      console.log(JSON.stringify(result, null, 2));
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+  data.command("set <database> <path> <value>").description(
+    `Set (overwrite) data at a path.
+
+Replaces whatever exists at the path with the given JSON value.
+Use "-" as the value to read JSON from stdin.
+
+Arguments:
+  database  Database ID (e.g. "users")
+  path      Path in the database (e.g. "/users/alice")
+  value     JSON value, or "-" to read from stdin
+
+Examples:
+  $ lark data set mydb / '{"key": "value"}'
+  $ lark data set mydb /users/alice '{"name": "Alice", "score": 100}'
+  $ cat data.json | lark data set mydb /path -`
+  ).action(async (database, path2, value) => {
+    const json = program2.opts().json;
+    try {
+      const projectId = resolveProject(program2.opts().project);
+      const body = value === "-" ? await readStdin() : value;
+      const parsed = JSON.parse(body);
+      const result = await dataRequest(projectId, "PUT", database, path2, parsed);
+      if (json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log("OK");
+      }
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+  data.command("update <database> <path> <value>").description(
+    `Update (merge) data at a path.
+
+Merges the given JSON into the existing data. Only the specified
+keys are changed; other keys are preserved. Use "-" to read
+from stdin.
+
+Arguments:
+  database  Database ID (e.g. "users")
+  path      Path in the database (e.g. "/users/alice")
+  value     JSON to merge, or "-" to read from stdin
+
+Examples:
+  $ lark data update mydb /users/alice '{"score": 150}'
+  $ lark data update mydb /config '{"theme": "dark"}'
+  $ echo '{"online": true}' | lark data update mydb /users/alice -`
+  ).action(async (database, path2, value) => {
+    const json = program2.opts().json;
+    try {
+      const projectId = resolveProject(program2.opts().project);
+      const body = value === "-" ? await readStdin() : value;
+      const parsed = JSON.parse(body);
+      const result = await dataRequest(projectId, "PATCH", database, path2, parsed);
+      if (json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log("OK");
+      }
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+  data.command("push <database> <path> <value>").description(
+    `Push data to a list, generating a unique key.
+
+Appends the value under an auto-generated key (like a list push).
+Returns the generated key name. Use "-" to read from stdin.
+
+Arguments:
+  database  Database ID (e.g. "chat")
+  path      Path to the list (e.g. "/messages")
+  value     JSON value, or "-" to read from stdin
+
+Examples:
+  $ lark data push chat /messages '{"from": "Alice", "text": "Hello"}'
+  $ echo '{"event": "login"}' | lark data push mydb /logs -`
+  ).action(async (database, path2, value) => {
+    const json = program2.opts().json;
+    try {
+      const projectId = resolveProject(program2.opts().project);
+      const body = value === "-" ? await readStdin() : value;
+      const parsed = JSON.parse(body);
+      const result = await dataRequest(projectId, "POST", database, path2, parsed);
+      if (json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(JSON.stringify(result, null, 2));
+      }
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+  data.command("delete <database> <path>").description(
+    'Delete data at a path.\n\nRemoves the value at the path. Parent nodes that become empty\nmay also be removed.\n\nArguments:\n  database  Database ID (e.g. "users")\n  path      Path to delete (e.g. "/users/alice")\n\nExamples:\n  $ lark data delete mydb /users/alice\n  $ lark data delete mydb /temp'
+  ).action(async (database, path2) => {
+    const json = program2.opts().json;
+    try {
+      const projectId = resolveProject(program2.opts().project);
+      await dataRequest(projectId, "DELETE", database, path2);
+      if (json) {
+        console.log(JSON.stringify({ success: true }));
+      } else {
+        console.log("Deleted.");
+      }
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+  data.command("export <database> [path]").description(
+    'Export database data as JSON.\n\nPrints the data as formatted JSON. Use -o to write to a file\ninstead of stdout. Path defaults to "/" (entire database).\n\nArguments:\n  database  Database ID (e.g. "users")\n  path      Path to export (default: "/")\n\nExamples:\n  $ lark data export mydb\n  $ lark data export mydb /users -o users.json\n  $ lark data export mydb / -o backup.json'
+  ).option("-o, --output <file>", "Write to file instead of stdout").action(async (database, path2, opts) => {
+    const json = program2.opts().json;
+    try {
+      const projectId = resolveProject(program2.opts().project);
+      const result = await dataRequest(projectId, "GET", database, path2 || "/");
+      const output = JSON.stringify(result, null, 2);
+      if (opts.output) {
+        fs2.writeFileSync(opts.output, output + "\n");
+        if (!json) {
+          console.log(`Exported to ${opts.output}`);
+        }
+      } else {
+        console.log(output);
+      }
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+  data.command("import <database> [path]").description(
+    'Import data from a JSON file.\n\nOverwrites data at the given path with the contents of the file.\nPath defaults to "/" (entire database).\n\nArguments:\n  database  Database ID (e.g. "users")\n  path      Path to import into (default: "/")\n\nExamples:\n  $ lark data import mydb -f backup.json\n  $ lark data import mydb /users -f users.json'
+  ).requiredOption("-f, --file <file>", "JSON file to import").action(async (database, path2, opts) => {
+    const json = program2.opts().json;
+    try {
+      const projectId = resolveProject(program2.opts().project);
+      const content = fs2.readFileSync(opts.file, "utf-8");
+      const parsed = JSON.parse(content);
+      await dataRequest(projectId, "PUT", database, path2 || "/", parsed);
+      if (json) {
+        console.log(JSON.stringify({ success: true }));
+      } else {
+        console.log(`Imported ${opts.file} to ${database}:${path2 || "/"}`);
+      }
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+  data.command("watch <database> <path>").description(
+    'Watch for real-time changes via SSE streaming.\n\nStreams live updates as they happen. Each change is printed\nas a line with the event type and data. Press Ctrl+C to stop.\n\nWith --json, outputs one JSON object per line (NDJSON).\n\nArguments:\n  database  Database ID (e.g. "chat")\n  path      Path to watch (e.g. "/messages")\n\nExamples:\n  $ lark data watch mydb /\n  $ lark data watch chat /messages\n  $ lark data watch mydb /users --json'
+  ).action(async (database, path2) => {
+    const jsonMode = program2.opts().json;
+    try {
+      const projectId = resolveProject(program2.opts().project);
+      const token = await getAdminToken(projectId);
+      const normalizedPath = path2.startsWith("/") ? path2 : `/${path2}`;
+      const url = `https://${projectId}.larkdb.net/${database}${normalizedPath}.json?v=2&auth=${token}`;
+      const res = await fetch(url, {
+        headers: { Accept: "text/event-stream" }
+      });
+      if (!res.ok || !res.body) {
+        throw new Error(`Failed to connect to SSE stream (${res.status})`);
+      }
+      if (!jsonMode) {
+        console.log(`Watching ${database}:${path2} \u2014 press Ctrl+C to stop
+`);
+      }
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      let eventType = "";
+      let eventData = "";
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop();
+        for (const line of lines) {
+          if (line.startsWith("event:")) {
+            eventType = line.slice(6).trim();
+          } else if (line.startsWith("data:")) {
+            eventData += line.slice(5).trim();
+          } else if (line === "") {
+            if (eventType && eventData) {
+              if (jsonMode) {
+                try {
+                  const parsed = JSON.parse(eventData);
+                  console.log(JSON.stringify({ event: eventType, data: parsed }));
+                } catch {
+                  console.log(JSON.stringify({ event: eventType, data: eventData }));
+                }
+              } else {
+                console.log(`[${eventType}] ${eventData}`);
+              }
+            }
+            eventType = "";
+            eventData = "";
+          }
+        }
+      }
+    } catch (err) {
+      handleError(err, jsonMode);
+    }
+  });
+}
+
+// src/commands/dashboard.ts
+function registerDashboardCommands(program2) {
+  program2.command("dashboard [id]").description(
+    "Show project dashboard with metrics and recent events.\n\nDisplays CCU, bandwidth, operations, and latency for the\ngiven time range (defaults to last 24 hours).\n\nUses the default project if no ID is given.\n\nExamples:\n  $ lark dashboard\n  $ lark dashboard my-app\n  $ lark dashboard --start 2026-02-01 --end 2026-02-15\n  $ lark dashboard --json"
+  ).option("--start <date>", 'Start date (ISO format, e.g. "2026-02-01")').option("--end <date>", 'End date (ISO format, e.g. "2026-02-15")').action(async (id, opts) => {
+    const json = program2.opts().json;
+    try {
+      const projectId = resolveProject(id || program2.opts().project);
+      const data = await admin.getDashboard(projectId, opts);
+      if (json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      console.log(`Dashboard: ${data.project.name} (${data.project.id})`);
+      console.log(`Period: ${data.time_range.start} to ${data.time_range.end}
+`);
+      if (data.current) {
+        console.log("--- Current ---");
+        keyValue({
+          "CCU": data.current.ccu,
+          "Peak CCU Today": data.current.peak_ccu_today,
+          "Bytes In Today": formatBytes(data.current.bytes_in_today),
+          "Bytes Out Today": formatBytes(data.current.bytes_out_today),
+          "Writes Today": data.current.writes_today,
+          "Reads Today": data.current.reads_today,
+          "Permission Denials": data.current.permission_denials
+        });
+        console.log();
+      }
+      if (data.summary) {
+        console.log("--- Summary ---");
+        keyValue({
+          "Peak CCU": data.summary.peak_ccu,
+          "Total Bytes In": formatBytes(data.summary.total_bytes_in),
+          "Total Bytes Out": formatBytes(data.summary.total_bytes_out),
+          "Total Writes": data.summary.total_writes,
+          "Total Reads": data.summary.total_reads,
+          "Total Events": data.summary.total_events,
+          "Avg Latency": formatLatency(data.summary.avg_latency_us)
+        });
+        console.log();
+      }
+      if (data.recent_events && data.recent_events.length > 0) {
+        console.log("--- Recent Events ---");
+        table(
+          data.recent_events.slice(0, 10).map((e) => ({
+            time: formatTime(e.ts),
+            database: e.database_id,
+            type: e.event_type,
+            message: e.message
+          }))
+        );
+      }
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+  program2.command("events [id]").description(
+    "Show project events (database connections, errors, etc.).\n\nUses the default project if no ID is given.\n\nExamples:\n  $ lark events\n  $ lark events my-app --limit 50\n  $ lark events --json"
+  ).option("--limit <n>", "Max results to return", "25").option("--offset <n>", "Number of results to skip", "0").action(async (id, opts) => {
+    const json = program2.opts().json;
+    try {
+      const projectId = resolveProject(id || program2.opts().project);
+      const result = await admin.getEvents(projectId, {
+        limit: parseInt(opts.limit),
+        offset: parseInt(opts.offset)
+      });
+      if (json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+      if (result.events.length === 0) {
+        console.log("No events.");
+        return;
+      }
+      table(
+        result.events.map((e) => ({
+          id: e.id,
+          time: formatTime(e.ts),
+          database: e.database_id,
+          type: e.event_type,
+          message: e.message
+        }))
+      );
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+  program2.command("billing [id]").description(
+    "Show project billing info for a given month.\n\nDefaults to the current billing period.\n\nExamples:\n  $ lark billing\n  $ lark billing my-app\n  $ lark billing --period 2026-01\n  $ lark billing --json"
+  ).option("--period <month>", 'Billing period in YYYY-MM format (e.g. "2026-01")').action(async (id, opts) => {
+    const json = program2.opts().json;
+    try {
+      const projectId = resolveProject(id || program2.opts().project);
+      const data = await admin.getBilling(projectId, opts.period);
+      if (json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      keyValue({
+        "Period": data.period_start,
+        "Peak CCU": data.peak_ccu,
+        "Total Bandwidth": formatBytes(data.total_bandwidth),
+        "Total Storage": formatBytes(data.total_storage)
+      });
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+}
+
+// src/commands/rules.ts
+import fs3 from "fs";
+function registerRulesCommands(program2) {
+  const rules = program2.command("rules").description(
+    "Manage project security rules.\n\nRules control read/write access to your database paths.\nThey use JSON5 format and follow Firebase-style syntax.\n\nExamples:\n  $ lark rules get\n  $ lark rules set -f rules.json"
+  );
+  rules.command("get [id]").description(
+    "Get the current security rules.\n\nPrints the raw rules JSON. Use --json to get a structured\nresponse with both the raw string and parsed object.\n\nExamples:\n  $ lark rules get\n  $ lark rules get my-app\n  $ lark rules get --json\n  $ lark rules get > rules-backup.json"
+  ).action(async (id) => {
+    const json = program2.opts().json;
+    try {
+      const projectId = resolveProject(id || program2.opts().project);
+      const project = await admin.getProject(projectId);
+      if (json) {
+        console.log(JSON.stringify({ rules_json: project.rules_json, rules: project.rules }, null, 2));
+        return;
+      }
+      if (project.rules_json) {
+        console.log(project.rules_json);
+      } else {
+        console.log("No rules configured.");
+      }
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+  rules.command("set [id]").description(
+    `Set security rules from a file or stdin.
+
+Accepts JSON5 format. Use -f to read from a file,
+or pipe rules via stdin.
+
+Examples:
+  $ lark rules set -f rules.json
+  $ lark rules set my-app -f rules.json5
+  $ cat rules.json | lark rules set
+  $ echo '{"rules": {".read": true}}' | lark rules set`
+  ).option("-f, --file <file>", "Rules file (JSON5 format)").action(async (id, opts) => {
+    const json = program2.opts().json;
+    try {
+      const projectId = resolveProject(id || program2.opts().project);
+      let rulesJson;
+      if (opts.file) {
+        rulesJson = fs3.readFileSync(opts.file, "utf-8");
+      } else {
+        rulesJson = await readStdin();
+      }
+      const project = await admin.updateProject(projectId, { rules_json: rulesJson.trim() });
+      if (json) {
+        console.log(JSON.stringify({ rules_json: project.rules_json, rules: project.rules }, null, 2));
+      } else {
+        console.log("Rules updated.");
+      }
+    } catch (err) {
+      handleError(err, json);
+    }
+  });
+}
+
+// src/index.ts
+var program = new Command();
+program.name("lark").description("CLI for Lark.sh \u2014 manage projects, databases, and data from the terminal.\n\nGet started:\n  $ lark login\n  $ lark config set-project <id>\n  $ lark data get mydb /\n\nDocs: https://docs.larksh.com (agent-friendly)\nMCP server: https://docs.larksh.com/mcp (provides the SearchLark tool)").version("0.1.0").option("--json", "Output results as machine-readable JSON").option("--project <id>", 'Project ID (overrides the default set by "config set-project")');
+registerAuthCommands(program);
+registerConfigCommands(program);
+registerProjectCommands(program);
+registerDatabaseCommands(program);
+registerDataCommands(program);
+registerDashboardCommands(program);
+registerRulesCommands(program);
+program.parse();

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@lark-sh/cli",
+  "version": "0.1.0",
+  "description": "CLI tool for Lark.sh — manage projects, databases, and data from the terminal",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lark-sh/lark-admin",
+    "directory": "cli"
+  },
+  "homepage": "https://lark.sh",
+  "keywords": ["lark", "larksh", "realtime", "database", "cli"],
+  "bin": {
+    "lark": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "open": "^10.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.1.0",
+    "typescript": "^5.5.0"
+  }
+}