clawon 0.1.5 → 0.1.7

package/README.md

@@ -0,0 +1,154 @@
+# Clawon
+
+Backup and restore your [OpenClaw](https://openclaw.ai) workspace. Move your memory, skills, and config between machines in one command.
+
+## Quick Start
+
+```bash
+# No install needed — runs with npx
+npx clawon discover          # Preview what will be backed up
+npx clawon local backup      # Save a local backup
+npx clawon local restore     # Restore from latest backup
+```
+
+## Commands
+
+### Local Backups (no account needed)
+
+Local backups are stored in `~/.clawon/backups/` as standard `.tar.gz` archives. You can inspect them with `tar tzf` or extract manually with `tar xzf`.
+
+```bash
+# Create a backup
+npx clawon local backup
+npx clawon local backup --tag "before migration"
+
+# List all local backups
+npx clawon local list
+
+# Restore
+npx clawon local restore                # Latest backup
+npx clawon local restore --pick 2       # Backup #2 from list
+npx clawon local restore --file path.tar.gz  # External file
+```
+
+### Cloud Backups (requires account)
+
+Cloud backups sync your workspace to Clawon's servers for cross-machine access.
+
+```bash
+# Authenticate
+npx clawon login --api-key <your-key>
+
+# Create a cloud backup
+npx clawon backup
+npx clawon backup --tag "stable config"
+npx clawon backup --dry-run             # Preview without uploading
+
+# List cloud backups
+npx clawon list
+
+# Restore from cloud
+npx clawon restore
+npx clawon restore --snapshot <id>      # Specific snapshot
+npx clawon restore --dry-run            # Preview without extracting
+
+# Manage snapshots
+npx clawon delete <id>
+npx clawon delete --oldest
+npx clawon files                        # List files in a cloud backup
+npx clawon activity                     # Recent events
+```
+
+### Other Commands
+
+```bash
+npx clawon discover    # Show exactly which files would be backed up
+npx clawon status      # Connection status and file count
+npx clawon logout      # Remove local credentials
+```
+
+## What Gets Backed Up
+
+Clawon uses an **allowlist** — only files matching these patterns are included:
+
+| Pattern | What it captures |
+|---------|-----------------|
+| `workspace/*.md` | Workspace markdown (memory, notes, identity) |
+| `workspace/memory/*.md` | Daily memory files |
+| `workspace/memory/**/*.md` | Nested memory (projects, workflows, experiments) |
+| `workspace/skills/**` | Custom skills |
+| `workspace/canvas/**` | Canvas data |
+| `skills/**` | Top-level skills |
+| `agents/*/config.json` | Agent configurations |
+
+Run `npx clawon discover` to see the exact file list for your instance.
+
+## What's Excluded
+
+These are **always excluded**, even if they match an include pattern:
+
+| Pattern | Why |
+|---------|-----|
+| `credentials/**` | API keys, tokens, auth files |
+| `openclaw.json` | May contain credentials |
+| `agents/*/sessions/**` | Ephemeral session data |
+| `memory/lancedb/**` | Vector database (binary, large) |
+| `memory/*.sqlite` | SQLite databases |
+| `*.lock`, `*.wal`, `*.shm` | Database lock files |
+| `node_modules/**` | Dependencies |
+
+**Credentials never leave your machine.** The entire `credentials/` directory and `openclaw.json` are excluded by default. You can verify this by running `npx clawon discover` before any backup.
+
+## Archive Format
+
+Local backups are standard gzip-compressed tar archives (`.tar.gz`). You can inspect and extract them with standard tools:
+
+```bash
+# List contents
+tar tzf ~/.clawon/backups/backup-2026-03-05T1030.tar.gz
+
+# Extract manually
+tar xzf ~/.clawon/backups/backup-2026-03-05T1030.tar.gz -C /tmp/inspect
+
+# View metadata
+tar xzf backup.tar.gz _clawon_meta.json -O | cat
+```
+
+Each archive contains:
+- `_clawon_meta.json` — metadata (version, date, tag, file count)
+- Your workspace files in their original directory structure
+
+## Data Storage
+
+| | Local | Cloud |
+|---|---|---|
+| **Location** | `~/.clawon/backups/` | Clawon servers (Supabase Storage) |
+| **Format** | `.tar.gz` | Individual files with signed URLs |
+| **Limit** | Unlimited | 2 snapshots (Starter), more on paid plans |
+| **Account required** | No | Yes |
+| **Cross-machine** | No (manual file transfer) | Yes |
+
+## Configuration
+
+Config is stored at `~/.clawon/config.json` after running `clawon login`. Contains your API key, profile ID, and API URL. Run `clawon logout` to remove it.
+
+## Telemetry
+
+Clawon collects anonymous usage events (e.g. "backup created", "restore completed") to understand which features are used. No file contents, filenames, or personal data are sent.
+
+**To opt out**, set either environment variable:
+
+```bash
+# Standard convention (https://consoledonottrack.com)
+export DO_NOT_TRACK=1
+
+# Or Clawon-specific
+export CLAWON_NO_TELEMETRY=1
+```
+
+Telemetry is powered by [PostHog](https://posthog.com). The public project key is visible in the source code.
+
+## Requirements
+
+- Node.js 18+
+- An OpenClaw installation at `~/.openclaw/`

package/dist/index.js

@@ -5,7 +5,7 @@ import { Command } from "commander";
 import fs from "fs";
 import path from "path";
 import os from "os";
-import zlib from "zlib";
+import * as tar from "tar";
 var CONFIG_DIR = path.join(os.homedir(), ".clawon");
 var CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 var OPENCLAW_DIR = path.join(os.homedir(), ".openclaw");
@@ -45,6 +45,7 @@ var INCLUDE_PATTERNS = [
 ];
 var EXCLUDE_PATTERNS = [
   "credentials/**",
+  "openclaw.json",
   "agents/*/sessions/**",
   "memory/lancedb/**",
   "memory/*.sqlite",
@@ -93,27 +94,53 @@ function discoverFiles(baseDir) {
   walk(baseDir);
   return files;
 }
-function createLocalArchive(files, openclawDir) {
-  const archiveFiles = files.map((f) => {
-    const fullPath = path.join(openclawDir, f.path);
-    const content = fs.readFileSync(fullPath).toString("base64");
-    return { path: f.path, size: f.size, content };
-  });
-  const archive = {
-    version: 1,
+async function createLocalArchive(files, openclawDir, outputPath, tag) {
+  const meta = {
+    version: 2,
     created: (/* @__PURE__ */ new Date()).toISOString(),
-    files: archiveFiles
+    ...tag ? { tag } : {},
+    file_count: files.length
   };
-  return zlib.gzipSync(JSON.stringify(archive));
+  const metaPath = path.join(openclawDir, "_clawon_meta.json");
+  fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2));
+  try {
+    await tar.create(
+      { gzip: true, file: outputPath, cwd: openclawDir },
+      ["_clawon_meta.json", ...files.map((f) => f.path)]
+    );
+  } finally {
+    fs.unlinkSync(metaPath);
+  }
 }
-function extractLocalArchive(archivePath) {
-  const compressed = fs.readFileSync(archivePath);
-  const json = zlib.gunzipSync(compressed).toString("utf8");
-  const archive = JSON.parse(json);
-  return { created: archive.created, files: archive.files };
+async function readArchiveMeta(archivePath) {
+  let meta = null;
+  await tar.list({
+    file: archivePath,
+    onReadEntry: (entry) => {
+      if (entry.path === "_clawon_meta.json") {
+        const chunks = [];
+        entry.on("data", (c) => chunks.push(c));
+        entry.on("end", () => {
+          meta = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        });
+      }
+    }
+  });
+  if (!meta) throw new Error("Invalid archive: missing _clawon_meta.json");
+  return meta;
+}
+async function extractLocalArchive(archivePath, targetDir) {
+  const meta = await readArchiveMeta(archivePath);
+  ensureDir(targetDir);
+  await tar.extract({ file: archivePath, cwd: targetDir, filter: (p) => p !== "_clawon_meta.json" });
+  return meta;
 }
 var POSTHOG_KEY = "phc_LGJC4ZrED6EiK0sC1fusErOhR6gHlFCS5Qs7ou93SmV";
+function telemetryDisabled() {
+  return process.env.DO_NOT_TRACK === "1" || process.env.CLAWON_NO_TELEMETRY === "1";
+}
 function trackCliEvent(distinctId, event, properties = {}) {
+  if (telemetryDisabled()) return;
   fetch("https://us.i.posthog.com/capture/", {
     method: "POST",
     headers: { "content-type": "application/json" },
@@ -148,7 +175,7 @@ program.command("login").description("Connect to Clawon with your API key").requ
     process.exit(1);
   }
 });
-program.command("backup").description("Backup your OpenClaw workspace to the cloud").option("--dry-run", "Show what would be backed up without uploading").action(async (opts) => {
+program.command("backup").description("Backup your OpenClaw workspace to the cloud").option("--dry-run", "Show what would be backed up without uploading").option("--tag <label>", "Add a label to this backup").action(async (opts) => {
   const cfg = readConfig();
   if (!cfg) {
     console.error("\u2717 Not logged in. Run: clawon login --api-key <key>");
@@ -188,7 +215,8 @@ program.command("backup").description("Backup your OpenClaw workspace to the clo
       cfg.apiKey,
       {
         profileId: cfg.profileId,
-        files: files.map((f) => ({ path: f.path, size: f.size }))
+        files: files.map((f) => ({ path: f.path, size: f.size })),
+        ...opts.tag ? { tag: opts.tag } : {}
       }
     );
     console.log(`Uploading ${files.length} files...`);
@@ -311,13 +339,14 @@ program.command("list").description("List your backups").option("--limit <n>", "
       return;
     }
     console.log("Your backups:\n");
-    console.log("ID                                   | Date                 | Files | Size");
-    console.log("\u2500".repeat(80));
+    console.log("ID                                   | Date                 | Files | Size     | Tag");
+    console.log("\u2500".repeat(100));
     for (const s of snapshots) {
       const date = new Date(s.created_at).toLocaleString();
       const size = s.size_bytes ? `${(s.size_bytes / 1024).toFixed(1)} KB` : "N/A";
       const files = s.changed_files_count || "N/A";
-      console.log(`${s.id} | ${date.padEnd(20)} | ${String(files).padEnd(5)} | ${size}`);
+      const tag = s.tag || "";
+      console.log(`${s.id} | ${date.padEnd(20)} | ${String(files).padEnd(5)} | ${String(size).padEnd(8)} | ${tag}`);
     }
     console.log(`
 Total: ${snapshots.length} backup(s)`);
@@ -422,6 +451,36 @@ program.command("delete [id]").description("Delete a snapshot").option("--oldest
     process.exit(1);
   }
 });
+program.command("discover").description("Preview which files would be included in a backup").action(async () => {
+  if (!fs.existsSync(OPENCLAW_DIR)) {
+    console.error(`\u2717 OpenClaw directory not found: ${OPENCLAW_DIR}`);
+    process.exit(1);
+  }
+  const files = discoverFiles(OPENCLAW_DIR);
+  if (files.length === 0) {
+    console.log("No files matched the include patterns.");
+    return;
+  }
+  const totalSize = files.reduce((sum, f) => sum + f.size, 0);
+  const tree = {};
+  for (const f of files) {
+    const dir = path.dirname(f.path);
+    if (!tree[dir]) tree[dir] = [];
+    tree[dir].push(f);
+  }
+  console.log(`Files that would be backed up:
+`);
+  for (const dir of Object.keys(tree).sort()) {
+    console.log(`\u{1F4C1} ${dir}/`);
+    for (const f of tree[dir]) {
+      const name = path.basename(f.path);
+      console.log(`   \u{1F4C4} ${name} (${f.size} bytes)`);
+    }
+  }
+  console.log(`
+Total: ${files.length} files (${(totalSize / 1024).toFixed(1)} KB)`);
+  console.log(`Source: ${OPENCLAW_DIR}`);
+});
 program.command("files").description("List files in a backup").option("--snapshot <id>", "Snapshot ID (default: latest)").action(async (opts) => {
   const cfg = readConfig();
   if (!cfg) {
@@ -463,7 +522,7 @@ Total: ${files.length} files`);
   }
 });
 var local = program.command("local").description("Local backup and restore (no cloud required)");
-local.command("backup").description("Save a local backup of your OpenClaw workspace").action(async () => {
+local.command("backup").description("Save a local backup of your OpenClaw workspace").option("--tag <label>", "Add a label to this backup").action(async (opts) => {
   if (!fs.existsSync(OPENCLAW_DIR)) {
     console.error(`\u2717 OpenClaw directory not found: ${OPENCLAW_DIR}`);
     process.exit(1);
@@ -476,18 +535,19 @@ local.command("backup").description("Save a local backup of your OpenClaw worksp
   }
   const totalSize = files.reduce((sum, f) => sum + f.size, 0);
   console.log(`Found ${files.length} files (${(totalSize / 1024).toFixed(1)} KB)`);
-  console.log("Creating archive...");
-  const archive = createLocalArchive(files, OPENCLAW_DIR);
   ensureDir(BACKUPS_DIR);
   const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "").replace("T", "T").slice(0, 15);
   const filename = `backup-${timestamp}.tar.gz`;
   const filePath = path.join(BACKUPS_DIR, filename);
-  fs.writeFileSync(filePath, archive);
+  console.log("Creating archive...");
+  await createLocalArchive(files, OPENCLAW_DIR, filePath, opts.tag);
+  const archiveSize = fs.statSync(filePath).size;
   console.log(`
 \u2713 Local backup saved!`);
   console.log(`  File: ${filePath}`);
   console.log(`  Files: ${files.length}`);
-  console.log(`  Size: ${(archive.length / 1024).toFixed(1)} KB (compressed)`);
+  console.log(`  Size: ${(archiveSize / 1024).toFixed(1)} KB (compressed)`);
+  if (opts.tag) console.log(`  Tag: ${opts.tag}`);
   const cfg = readConfig();
   trackCliEvent(cfg?.profileId || "anonymous", "local_backup_created", {
     file_count: files.length,
@@ -505,19 +565,21 @@ local.command("list").description("List local backups").action(async () => {
     return;
   }
   console.log("Local backups:\n");
-  console.log("#  | Date                      | Files | Size     | Path");
-  console.log("\u2500".repeat(100));
+  console.log("#  | Date                      | Files | Size     | Tag                  | Path");
+  console.log("\u2500".repeat(120));
   for (let i = 0; i < entries.length; i++) {
     const filePath = path.join(BACKUPS_DIR, entries[i]);
     try {
-      const { created, files } = extractLocalArchive(filePath);
-      const totalSize = files.reduce((sum, f) => sum + f.size, 0);
-      const date = new Date(created).toLocaleString();
+      const meta = await readArchiveMeta(filePath);
+      const date = new Date(meta.created).toLocaleString();
+      const archiveSize = fs.statSync(filePath).size;
+      const sizeStr = `${(archiveSize / 1024).toFixed(1)} KB`;
+      const tagStr = (meta.tag || "").padEnd(20);
       console.log(
-        `${String(i + 1).padStart(2)} | ${date.padEnd(25)} | ${String(files.length).padEnd(5)} | ${(totalSize / 1024).toFixed(1).padEnd(8)} KB | ${filePath}`
+        `${String(i + 1).padStart(2)} | ${date.padEnd(25)} | ${String(meta.file_count).padEnd(5)} | ${sizeStr.padEnd(10)} | ${tagStr} | ${filePath}`
       );
     } catch {
-      console.log(`${String(i + 1).padStart(2)} | ${entries[i].padEnd(25)} | ???   | ???        | ${filePath}`);
+      console.log(`${String(i + 1).padStart(2)} | ${entries[i].padEnd(25)} | ???   | ???        |                      | ${filePath}`);
     }
   }
   console.log(`
@@ -559,26 +621,19 @@ local.command("restore").description("Restore from a local backup").option("--fi
   }
   console.log(`Restoring from: ${archivePath}`);
   try {
-    const { created, files } = extractLocalArchive(archivePath);
-    const totalSize = files.reduce((sum, f) => sum + f.size, 0);
-    console.log(`Backup date: ${new Date(created).toLocaleString()}`);
-    console.log(`Files: ${files.length} (${(totalSize / 1024).toFixed(1)} KB)`);
-    let restored = 0;
-    for (const file of files) {
-      const targetPath = path.join(OPENCLAW_DIR, file.path);
-      ensureDir(path.dirname(targetPath));
-      fs.writeFileSync(targetPath, Buffer.from(file.content, "base64"));
-      restored++;
-      process.stdout.write(`\r  Restored: ${restored}/${files.length}`);
-    }
-    console.log("");
+    const meta = await readArchiveMeta(archivePath);
+    console.log(`Backup date: ${new Date(meta.created).toLocaleString()}`);
+    console.log(`Files: ${meta.file_count}`);
+    if (meta.tag) console.log(`Tag: ${meta.tag}`);
+    console.log("\nExtracting...");
+    await extractLocalArchive(archivePath, OPENCLAW_DIR);
     console.log(`
 \u2713 Restore complete!`);
     console.log(`  Restored to: ${OPENCLAW_DIR}`);
-    console.log(`  Files: ${files.length}`);
+    console.log(`  Files: ${meta.file_count}`);
     const cfg = readConfig();
     trackCliEvent(cfg?.profileId || "anonymous", "local_backup_restored", {
-      file_count: files.length,
+      file_count: meta.file_count,
       source: opts.file ? "file" : "local"
     });
   } catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawon",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Backup and restore your OpenClaw workspace",
   "type": "module",
   "bin": {
@@ -24,7 +24,8 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "commander": "^12.1.0"
+    "commander": "^12.1.0",
+    "tar": "^7.5.10"
   },
   "devDependencies": {
     "tsup": "^8.2.4",