htmlhost-cli 2.1.6 → 2.2.0

package/README.md

@@ -79,8 +79,58 @@ automatically inlined or uploaded and rewritten to hosted URLs.
 | `--title <title>` | Set the site title |
 | `--new` | Force new site (ignore .htmlhost link) |
 | `--no-assets` | Skip automatic asset processing (single-file only) |
+| `--no-pull-check` | Skip remote change detection before deploy |
 | `--json` | Output result as JSON (for CI/CD) |
 
+**Sync check on re-deploy:** When re-deploying to a linked site, the CLI automatically
+checks if the remote site was modified (e.g. via the web editor) since your last deploy
+or pull. If changes are detected, you'll be prompted to pull first, deploy anyway, or
+cancel. Use `--no-pull-check` to skip this check (useful in CI/CD).
+
+### `htmlhost pull [slug] [options]`
+Pull remote changes from an htmlhost.co site to the local project.
+
+```bash
+# Pull changes for the linked site
+htmlhost pull
+
+# Pull a specific site
+htmlhost pull my-site
+
+# Pull without confirmation
+htmlhost pull --force
+
+# Show what would change without writing
+htmlhost pull --dry-run
+```
+
+When you (or a collaborator) edit a site through the web editor, those changes live on
+the server. `htmlhost pull` downloads them to your local project so you can continue
+working locally.
+
+| Option | Description |
+|---|---|
+| `--force`, `-f` | Pull without confirmation prompt |
+| `--dry-run` | Show what would change without writing files |
+
+### `htmlhost clone <slug> [directory]`
+Clone a deployed site into a local directory for continued development.
+
+```bash
+# Clone into a new directory named after the slug
+htmlhost clone my-site
+# → creates ./my-site/ with all files + .htmlhost link
+
+# Clone into a specific directory
+htmlhost clone my-site ./my-project
+```
+
+This is useful for sites that were originally created through the web editor and
+haven't been deployed from the CLI before. After cloning, use `htmlhost deploy` to
+push changes and `htmlhost pull` to sync remote edits.
+
+Use `--force` to overwrite an existing non-empty directory.
+
 ### `htmlhost list`
 List all your sites with titles, sizes, TTL, and expiry. Multi-page sites are marked with 📄.
 
@@ -115,3 +165,7 @@ Credentials are stored in `~/.htmlhostrc`:
 ## License
 
 MIT
+
+### Free publishing allowance
+
+Free publishing is limited. Subscribe to Pro to continue creating unlimited sites at https://htmlhost.co/upgrade. See Pro benefits at https://htmlhost.co/pricing. Before your first free CLI deployment, sign in at https://htmlhost.co/new to complete browser verification. If verification is unavailable, contact hey@htmlhost.co for review.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "htmlhost-cli",
-  "version": "2.1.6",
+  "version": "2.2.0",
   "description": "Deploy HTML files from the terminal — htmlhost.co CLI",
   "type": "module",
   "bin": {

package/src/api.mjs

@@ -112,3 +112,15 @@ export async function uploadFile(path, filePath, fileName, mimeType) {
   }, `upload ${fileName}`);
 }
 
+/**
+ * Download a file from a URL as a Buffer.
+ * Used for fetching binary assets via presigned R2 download URLs.
+ * No auth header needed — presigned URLs are self-authenticating.
+ */
+export async function downloadBuffer(url) {
+  const res = await fetch(url);
+  if (!res.ok) throw new ApiError(`Download failed: HTTP ${res.status}`, res.status);
+  const arrayBuffer = await res.arrayBuffer();
+  return Buffer.from(arrayBuffer);
+}
+

package/src/cli.mjs

@@ -4,13 +4,15 @@
 import { bold, dim, cyan, err } from "./ui.mjs";
 import { ApiError } from "./api.mjs";
 
-const VERSION = "2.1.6";
+const VERSION = "2.2.0";
 
 const HELP = `
   ${bold("htmlhost")} ${dim(`v${VERSION}`)} — deploy HTML from the terminal
 
   ${bold("Usage:")}
     ${cyan("htmlhost deploy")} [file|dir] [opts]  Deploy file or directory
+    ${cyan("htmlhost pull")} [slug] [opts]        Pull remote changes to local
+    ${cyan("htmlhost clone")} <slug> [dir]        Clone a site to a local directory
     ${cyan("htmlhost list")}                     List your sites
     ${cyan("htmlhost delete")} <slug>            Delete a site
     ${cyan("htmlhost login")}                    Authenticate with an API token
@@ -24,6 +26,11 @@ const HELP = `
     --title <title>   Set the site title
     --new             Force a new site (ignore .htmlhost link)
     --no-assets       Skip auto-uploading local assets (single-file only)
+    --no-pull-check   Skip remote change detection before deploy
+
+  ${bold("Pull options:")}
+    --force, -f       Pull without confirmation prompt
+    --dry-run         Show what would change without writing
 
   ${bold("Delete options:")}
     --force, -f       Skip confirmation prompt
@@ -33,6 +40,7 @@ const HELP = `
     Single file:    deploys just that file (assets auto-inlined)
     Linked:         reads ${dim(".htmlhost")}, updates the same site
     Local CSS, JS, images, and fonts are auto-uploaded
+    On re-deploy, checks for remote changes and offers to pull first
 
   ${bold("Examples:")}
     ${dim("$")} htmlhost deploy                ${dim("# deploys cwd as a site")}
@@ -41,6 +49,10 @@ const HELP = `
     ${dim("$")} htmlhost deploy --ttl 30d      ${dim("# deploy with 30-day TTL")}
     ${dim("$")} htmlhost deploy --new          ${dim("# force new site")}
     ${dim("$")} htmlhost deploy --json         ${dim("# JSON output for CI/CD")}
+    ${dim("$")} htmlhost pull                  ${dim("# pull remote changes")}
+    ${dim("$")} htmlhost pull my-site --force  ${dim("# pull without prompting")}
+    ${dim("$")} htmlhost clone my-site         ${dim("# clone into ./my-site/")}
+    ${dim("$")} htmlhost clone my-site ./proj  ${dim("# clone into ./proj/")}
     ${dim("$")} htmlhost delete old-project --force
 
   ${bold("Update:")}
@@ -93,6 +105,16 @@ export async function run(argv) {
         await deploy(args, { json: jsonMode });
         break;
       }
+      case "pull": {
+        const { pull } = await import("./commands/pull.mjs");
+        await pull(args);
+        break;
+      }
+      case "clone": {
+        const { clone } = await import("./commands/clone.mjs");
+        await clone(args);
+        break;
+      }
       case "list":
       case "ls": {
         const { list } = await import("./commands/list.mjs");

package/src/commands/clone.mjs

@@ -0,0 +1,178 @@
+/**
+ * htmlhost clone <slug> [dir] [--force]
+ *
+ * Clone a deployed htmlhost.co site into a local directory.
+ * Creates a new folder (named after the slug by default), downloads all
+ * pages and assets, and sets up the .htmlhost link file so future deploys
+ * update the same site.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { get, downloadBuffer } from "../api.mjs";
+import {
+  ok,
+  err,
+  info,
+  warn,
+  cyan,
+  dim,
+  bold,
+  green,
+  yellow,
+  confirm,
+  formatBytes,
+} from "../ui.mjs";
+
+const LINK_FILE = ".htmlhost";
+
+/**
+ * Map a page path to a local file path.
+ * "/" → "index.html", "/about" → "about.html"
+ */
+function pagePathToFile(pagePath) {
+  if (pagePath === "/") return "index.html";
+  const clean = pagePath.replace(/^\//, "");
+  if (!clean.includes(".")) return `${clean}.html`;
+  return clean;
+}
+
+/**
+ * Main clone command.
+ */
+export async function clone(args) {
+  const positionals = args.filter((a) => !a.startsWith("--"));
+  const slug = positionals[0];
+  const targetDir = positionals[1]; // optional — defaults to slug name
+  const force = args.includes("--force") || args.includes("-f");
+
+  if (!slug) {
+    err(
+      "Usage: htmlhost clone <slug> [directory]\n" +
+        `    ${cyan("htmlhost clone my-site")}        ${dim("# clones into ./my-site/")}\n` +
+        `    ${cyan("htmlhost clone my-site ./proj")}  ${dim("# clones into ./proj/")}`
+    );
+    process.exit(1);
+  }
+
+  // Strip .htmlhost.co suffix if provided
+  const cleanSlug = slug.endsWith(".htmlhost.co")
+    ? slug.replace(".htmlhost.co", "")
+    : slug;
+
+  const destDir = resolve(targetDir || cleanSlug);
+
+  // Check if directory already exists and is non-empty
+  if (existsSync(destDir)) {
+    try {
+      const entries = readdirSync(destDir);
+      if (entries.length > 0 && !force) {
+        err(
+          `Directory ${cyan(destDir)} already exists and is not empty.\n` +
+            `    Use ${cyan("--force")} to overwrite, or ${cyan("htmlhost pull")} to sync an existing project.`
+        );
+        process.exit(1);
+      }
+    } catch {
+      // Not a directory — error
+      err(`${destDir} exists but is not a directory.`);
+      process.exit(1);
+    }
+  }
+
+  console.log("");
+  info(`Cloning ${cyan(bold(cleanSlug + ".htmlhost.co"))}…`);
+
+  // Fetch remote content
+  let data;
+  try {
+    data = await get(`/api/sites/pull?slug=${encodeURIComponent(cleanSlug)}`);
+  } catch (e) {
+    err(`Failed to fetch site: ${e.message}`);
+    process.exit(1);
+  }
+
+  const pageCount = (data.pages || []).length;
+  const assetCount = (data.assets || []).length;
+  const totalFiles = pageCount + assetCount;
+
+  console.log(
+    `  ${dim(`Version ${data.version} · ${pageCount} page${pageCount !== 1 ? "s" : ""} · ${assetCount} asset${assetCount !== 1 ? "s" : ""}`)}`
+  );
+  console.log("");
+
+  // Create destination directory
+  mkdirSync(destDir, { recursive: true });
+
+  let written = 0;
+
+  // --- Write HTML pages ---
+  for (const page of data.pages || []) {
+    const localFile = pagePathToFile(page.path);
+    const localPath = join(destDir, localFile);
+    mkdirSync(dirname(localPath), { recursive: true });
+    writeFileSync(localPath, page.html, "utf8");
+    written++;
+    ok(`${cyan(localFile)} ${dim(`(${formatBytes(page.sizeBytes || Buffer.byteLength(page.html))})`)}`);
+  }
+
+  // --- Write assets ---
+  for (const asset of data.assets || []) {
+    const localPath = join(destDir, asset.path);
+    mkdirSync(dirname(localPath), { recursive: true });
+
+    if (asset.content !== null && asset.content !== undefined) {
+      // Text asset — write inline content
+      writeFileSync(localPath, asset.content, "utf8");
+    } else if (asset.downloadUrl) {
+      // Binary asset — download
+      const buf = await downloadBuffer(asset.downloadUrl);
+      writeFileSync(localPath, buf);
+    } else {
+      warn(`Skipping ${cyan(asset.path)} — no content available`);
+      continue;
+    }
+
+    written++;
+    ok(`${cyan(asset.path)} ${dim(`(${formatBytes(asset.sizeBytes)})`)}`);
+  }
+
+  // --- Write .htmlhost link file ---
+  const isMultiPage = pageCount > 1;
+  const linkData = isMultiPage
+    ? {
+        multipage: {
+          slug: cleanSlug,
+          url: `${cleanSlug}.htmlhost.co`,
+          pageCount,
+        },
+        sync: {
+          version: data.version,
+          updatedAt: data.updatedAt,
+          pulledAt: new Date().toISOString(),
+        },
+      }
+    : {
+        slug: cleanSlug,
+        url: `${cleanSlug}.htmlhost.co`,
+        sync: {
+          version: data.version,
+          updatedAt: data.updatedAt,
+          pulledAt: new Date().toISOString(),
+        },
+      };
+
+  const linkPath = join(destDir, LINK_FILE);
+  writeFileSync(linkPath, JSON.stringify(linkData, null, 2) + "\n", "utf8");
+
+  // --- Done ---
+  console.log("");
+  console.log(`  ${green("━".repeat(40))}`);
+  ok(
+    `Cloned ${bold(String(written))} file${written === 1 ? "" : "s"} into ${cyan(destDir)}`
+  );
+  console.log(`   ${dim(`Linked → .htmlhost · ${cleanSlug}.htmlhost.co`)}`);
+  console.log("");
+  console.log(`   ${dim("Deploy changes:")}  ${cyan("htmlhost deploy")}`);
+  console.log(`   ${dim("Pull updates:")}    ${cyan("htmlhost pull")}`);
+  console.log("");
+}

package/src/commands/deploy.mjs

@@ -1,8 +1,10 @@
-import { readFileSync, writeFileSync, statSync, existsSync, readdirSync } from "node:fs";
+import { readFileSync, writeFileSync, statSync, existsSync, readdirSync, mkdirSync } from "node:fs";
 import { basename, resolve, dirname, join, extname } from "node:path";
 import { createInterface } from "node:readline";
+import { createHash } from "node:crypto";
 import { post } from "../api.mjs";
 import { ok, err, info, cyan, dim, bold, yellow, green, formatBytes, mimeFromExt } from "../ui.mjs";
+import { checkRemoteChanges } from "./pull.mjs";
 
 const LINK_FILE = ".htmlhost";
 
@@ -114,6 +116,7 @@ export async function deploy(args, { json = false } = {}) {
   const slug = getFlag(args, "--slug");
   const forceNew = args.includes("--new");
   const skipAssets = args.includes("--no-assets");
+  const skipPullCheck = args.includes("--no-pull-check");
 
   // Resolve target
   const targetPath = resolve(target || ".");
@@ -128,17 +131,17 @@ export async function deploy(args, { json = false } = {}) {
 
   // --- Directory deploy (default) ---
   if (stat.isDirectory()) {
-    return deployDirectory(targetPath, { ttl, title, slug, forceNew, json });
+    return deployDirectory(targetPath, { ttl, title, slug, forceNew, json, skipPullCheck });
   }
 
   // --- Single-file deploy ---
-  await deploySingleFile(target || "index.html", { ttl, title, forceNew, skipAssets, slug, json });
+  await deploySingleFile(target || "index.html", { ttl, title, forceNew, skipAssets, slug, json, skipPullCheck });
 }
 
 /**
  * Deploy a single HTML file (existing behavior preserved).
  */
-async function deploySingleFile(file, { ttl, title, forceNew, skipAssets, slug, json }) {
+async function deploySingleFile(file, { ttl, title, forceNew, skipAssets, slug, json, skipPullCheck }) {
   const filePath = resolve(file);
   const projectDir = dirname(filePath);
   const fileName = basename(filePath);
@@ -227,6 +230,12 @@ async function deploySingleFile(file, { ttl, title, forceNew, skipAssets, slug,
 
   info(slug ? `Re-deploying to ${cyan(slug)}…` : "Deploying new site…");
 
+  // --- Pre-deploy remote change check (single-file) ---
+  if (slug && !skipPullCheck) {
+    const aborted = await preDeployPullCheck(slug, projectDir);
+    if (aborted) return;
+  }
+
   const body = { html };
   if (ttl) body.ttl = ttl;
   if (slug) body.slug = slug;
@@ -240,6 +249,11 @@ async function deploySingleFile(file, { ttl, title, forceNew, skipAssets, slug,
     slug: data.slug,
     url: data.url,
     ...(existingLink?.onRedeploy ? { onRedeploy: existingLink.onRedeploy } : {}),
+    sync: {
+      version: data.version,
+      updatedAt: new Date().toISOString(),
+      deployedAt: new Date().toISOString(),
+    },
   });
 
   if (json) {
@@ -270,7 +284,7 @@ async function deploySingleFile(file, { ttl, title, forceNew, skipAssets, slug,
  * Non-HTML files (CSS, JS, images, fonts) are uploaded via the media endpoint
  * and included as pages with their hosted URLs.
  */
-async function deployDirectory(dirPath, { ttl, title, slug: explicitSlug, forceNew, json }) {
+async function deployDirectory(dirPath, { ttl, title, slug: explicitSlug, forceNew, json, skipPullCheck }) {
   // Find all files recursively
   const allFiles = findAllFiles(dirPath, dirPath);
 
@@ -302,6 +316,12 @@ async function deployDirectory(dirPath, { ttl, title, slug: explicitSlug, forceN
   console.log("");
   if (existingSlug) {
     info(`Re-deploying to ${cyan(bold(existingSlug + ".htmlhost.co"))}`);
+
+    // --- Pre-deploy remote change check ---
+    if (!skipPullCheck) {
+      const aborted = await preDeployPullCheck(existingSlug, dirPath);
+      if (aborted) return;
+    }
   } else {
     info(`Deploying ${cyan(bold(basename(dirPath) || "."))} as a new site`);
   }
@@ -384,11 +404,18 @@ async function deployDirectory(dirPath, { ttl, title, slug: explicitSlug, forceN
       slug: existingSlug || undefined,
       isNewSite: !existingSlug,
       html: pagePayloads[0]?.html || "",
-      assets: assetFiles.map(f => ({
-        path: f.relativePath,
-        sizeBytes: f.size,
-        mimeType: mimeFromExt(basename(f.filePath))
-      }))
+      assets: assetFiles.map(f => {
+        const buffer = readFileSync(f.filePath);
+        const hash = createHash('sha256').update(buffer).digest('hex');
+        // Store buffer on file object to avoid reading again
+        f.buffer = buffer;
+        return {
+          path: f.relativePath,
+          sizeBytes: f.size,
+          mimeType: mimeFromExt(basename(f.filePath)),
+          hash
+        };
+      })
     };
     
     let urlData;
@@ -404,29 +431,37 @@ async function deployDirectory(dirPath, { ttl, title, slug: explicitSlug, forceN
     console.log("");
     info(`Uploading ${cyan(bold(String(assetFiles.length)))} asset${assetFiles.length > 1 ? "s" : ""}…`);
     
+    let uploadedCount = 0;
+    let skippedCount = 0;
+
     for (const u of uploadUrls) {
       const file = assetFiles.find(f => f.relativePath === u.path);
-      const buffer = readFileSync(file.filePath);
-      
-      const res = await fetch(u.uploadUrl, {
-        method: "PUT",
-        headers: { "Content-Type": u.mimeType },
-        body: buffer
-      });
       
-      if (!res.ok) {
-        err(`Failed to upload ${u.path}`);
-        process.exit(1);
+      if (u.uploadUrl) {
+        const res = await fetch(u.uploadUrl, {
+          method: "PUT",
+          headers: { "Content-Type": u.mimeType },
+          body: file.buffer
+        });
+        
+        if (!res.ok) {
+          err(`Failed to upload ${u.path}`);
+          process.exit(1);
+        }
+        ok(`✓ Uploaded ${cyan(u.path)} ${dim(`(${formatBytes(file.size)})`)}`);
+        uploadedCount++;
+      } else {
+        ok(`● Skipped (unchanged) ${cyan(u.path)} ${dim(`(${formatBytes(file.size)})`)}`);
+        skippedCount++;
       }
       
       assetPayloads.push({
         path: u.path,
         mimeType: u.mimeType,
         sizeBytes: u.sizeBytes,
-        storageKey: u.storageKey
+        storageKey: u.storageKey,
+        hash: u.hash
       });
-      
-      ok(`✓ Uploaded ${cyan(u.path)} ${dim(`(${formatBytes(file.size)})`)}`);
     }
     
     if (!existingSlug) {
@@ -459,6 +494,11 @@ async function deployDirectory(dirPath, { ttl, title, slug: explicitSlug, forceN
         url: data.url,
         pageCount: data.pageCount || pagePayloads.length,
       },
+      sync: {
+        version: data.version,
+        updatedAt: new Date().toISOString(),
+        deployedAt: new Date().toISOString(),
+      },
     });
 
     if (json) {
@@ -485,6 +525,62 @@ async function deployDirectory(dirPath, { ttl, title, slug: explicitSlug, forceN
   }
 }
 
+/**
+ * Pre-deploy check: compare local sync version with remote version.
+ * If remote is newer, prompt the user to pull, deploy anyway, or cancel.
+ *
+ * Returns true if the deploy should be aborted (user cancelled or pulled).
+ * Returns false to continue the deploy.
+ */
+async function preDeployPullCheck(slug, projectDir) {
+  const link = readLink(projectDir);
+  const localVersion = link?.sync?.version;
+
+  // If we've never synced, skip the check — nothing to compare against
+  if (!localVersion) return false;
+
+  const remote = await checkRemoteChanges(slug);
+  if (!remote) return false; // network error — don't block the deploy
+
+  if (remote.version <= localVersion) return false; // up to date
+
+  // Remote has changes!
+  console.log("");
+  console.log(`  ${yellow("!")} ${bold("Remote changes detected")} — ${cyan(slug + ".htmlhost.co")} was modified since your last deploy.`);
+  console.log(`    ${dim(`Remote version: ${remote.version} · Local version: ${localVersion}`)}`);
+  console.log("");
+
+  const choice = await promptChoice(
+    "What would you like to do?",
+    [
+      "Pull changes first, then deploy",
+      `Deploy anyway ${dim("(overwrites remote changes)")}`,
+      "Cancel",
+    ]
+  );
+
+  switch (choice) {
+    case 0: {
+      // Pull first
+      const { pull } = await import("./pull.mjs");
+      await pull([slug, "--force"]);
+      // After pulling, the user needs to re-run deploy to pick up the merged content
+      console.log("");
+      info(`${dim("Run")} ${cyan("htmlhost deploy")} ${dim("again to deploy with the pulled changes.")}`);
+      console.log("");
+      return true; // abort current deploy
+    }
+    case 1:
+      // Deploy anyway — continue
+      return false;
+    case 2:
+    case -1:
+    default:
+      console.log("  Cancelled.");
+      process.exit(0);
+  }
+}
+
 /**
  * Recursively find all files in a directory.
  * Skips ignored files/directories.

package/src/commands/pull.mjs

@@ -0,0 +1,319 @@
+/**
+ * htmlhost pull [slug] [--force] [--dry-run]
+ *
+ * Pull remote changes from an htmlhost.co site to the local project.
+ * Reads .htmlhost to find the linked slug, or accepts a slug argument.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from "node:fs";
+import { join, dirname, resolve, basename } from "node:path";
+import { createHash } from "node:crypto";
+import { get, downloadBuffer } from "../api.mjs";
+import {
+  ok,
+  err,
+  info,
+  warn,
+  cyan,
+  dim,
+  bold,
+  green,
+  yellow,
+  confirm,
+  formatBytes,
+} from "../ui.mjs";
+
+const LINK_FILE = ".htmlhost";
+
+/**
+ * Read the project link from .htmlhost
+ */
+function readLink(dir) {
+  const linkPath = join(dir, LINK_FILE);
+  if (!existsSync(linkPath)) return null;
+  try {
+    return JSON.parse(readFileSync(linkPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save project link to .htmlhost
+ */
+function writeLink(dir, data) {
+  const linkPath = join(dir, LINK_FILE);
+  writeFileSync(linkPath, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+/**
+ * Map a page path back to a local file path.
+ * "/" → "index.html", "/about" → "about.html", "/blog" → "blog/index.html" or "blog.html"
+ */
+function pagePathToFile(pagePath) {
+  if (pagePath === "/") return "index.html";
+  const clean = pagePath.replace(/^\//, "");
+  // If it looks like a directory (no extension), append .html
+  if (!clean.includes(".")) return `${clean}.html`;
+  return clean;
+}
+
+/**
+ * Compare local file content with remote content.
+ * Returns null if identical, or an object describing the diff.
+ */
+function diffFile(localPath, remoteContent) {
+  if (!existsSync(localPath)) {
+    return { type: "new", sizeBytes: Buffer.byteLength(remoteContent) };
+  }
+  const localContent = readFileSync(localPath, "utf8");
+  if (localContent === remoteContent) return null;
+  return {
+    type: "modified",
+    localSize: Buffer.byteLength(localContent),
+    remoteSize: Buffer.byteLength(remoteContent),
+  };
+}
+
+
+/**
+ * Main pull command.
+ */
+export async function pull(args) {
+  const slugArg = args.find((a) => !a.startsWith("--"));
+  const force = args.includes("--force") || args.includes("-f");
+  const dryRun = args.includes("--dry-run");
+
+  const projectDir = resolve(".");
+  const link = readLink(projectDir);
+
+  // Resolve slug
+  let slug = slugArg;
+  if (!slug) {
+    if (link?.multipage?.slug) {
+      slug = link.multipage.slug;
+    } else if (link?.slug) {
+      slug = link.slug;
+    }
+  }
+
+  if (!slug) {
+    err(
+      "No site linked. Provide a slug or deploy first:\n" +
+        `    ${cyan("htmlhost pull <slug>")}\n` +
+        `    ${cyan("htmlhost deploy")} ${dim("(creates .htmlhost link)")}`
+    );
+    process.exit(1);
+  }
+
+  // Strip .htmlhost.co suffix if provided
+  if (slug.endsWith(".htmlhost.co")) {
+    slug = slug.replace(".htmlhost.co", "");
+  }
+
+  console.log("");
+  info(`Pulling from ${cyan(bold(slug + ".htmlhost.co"))}…`);
+
+  // Fetch remote content
+  let data;
+  try {
+    data = await get(`/api/sites/pull?slug=${encodeURIComponent(slug)}`);
+  } catch (e) {
+    err(`Failed to fetch site: ${e.message}`);
+    process.exit(1);
+  }
+
+  console.log(`  ${dim(`Version ${data.version} · Updated ${relTime(data.updatedAt)}`)}`);
+  console.log("");
+
+  // Build list of changes
+  const changes = [];
+
+  // --- Pages (HTML) ---
+  for (const page of data.pages || []) {
+    const localFile = pagePathToFile(page.path);
+    const localPath = join(projectDir, localFile);
+    const diff = diffFile(localPath, page.html);
+
+    if (diff) {
+      changes.push({
+        file: localFile,
+        ...diff,
+        write: () => {
+          mkdirSync(dirname(localPath), { recursive: true });
+          writeFileSync(localPath, page.html, "utf8");
+        },
+      });
+    }
+  }
+
+  // --- Assets (CSS/JS/binary) ---
+  for (const asset of data.assets || []) {
+    const localPath = join(projectDir, asset.path);
+
+    if (asset.content !== null && asset.content !== undefined) {
+      // Text asset — inline content
+      const diff = diffFile(localPath, asset.content);
+      if (diff) {
+        changes.push({
+          file: asset.path,
+          ...diff,
+          write: () => {
+            mkdirSync(dirname(localPath), { recursive: true });
+            writeFileSync(localPath, asset.content, "utf8");
+          },
+        });
+      }
+    } else if (asset.downloadUrl) {
+      // Binary asset — need to download
+      // Check if local file exists and compare hash/size
+      let needsDownload = false;
+      let changeType = "new";
+
+      if (!existsSync(localPath)) {
+        needsDownload = true;
+        changeType = "new";
+      } else if (asset.hash) {
+        // Compare hash
+        const localBuffer = readFileSync(localPath);
+        const localHash = createHash("sha256")
+          .update(localBuffer)
+          .digest("hex");
+        if (localHash !== asset.hash) {
+          needsDownload = true;
+          changeType = "modified";
+        }
+      } else {
+        // Fallback: compare size
+        try {
+          const localSize = statSync(localPath).size;
+          if (localSize !== asset.sizeBytes) {
+            needsDownload = true;
+            changeType = "modified";
+          }
+        } catch {
+          needsDownload = true;
+        }
+      }
+
+      if (needsDownload) {
+        changes.push({
+          file: asset.path,
+          type: changeType,
+          sizeBytes: asset.sizeBytes,
+          write: async () => {
+            const buf = await downloadBuffer(asset.downloadUrl);
+            mkdirSync(dirname(localPath), { recursive: true });
+            writeFileSync(localPath, buf);
+          },
+        });
+      }
+    }
+  }
+
+  // --- Show results ---
+  if (changes.length === 0) {
+    ok("Already up to date — no changes to pull.");
+    console.log("");
+    // Update sync state even if nothing changed
+    updateSyncState(projectDir, link, slug, data.version, data.updatedAt);
+    return;
+  }
+
+  // Group changes by type
+  const newFiles = changes.filter((c) => c.type === "new");
+  const modifiedFiles = changes.filter((c) => c.type === "modified");
+
+  for (const c of newFiles) {
+    console.log(`   ${green("+")} ${bold("New:")}       ${cyan(c.file)} ${dim(`(${formatBytes(c.sizeBytes)})`)}`);
+  }
+  for (const c of modifiedFiles) {
+    console.log(`   ${yellow("~")} ${bold("Modified:")} ${cyan(c.file)}`);
+  }
+  console.log("");
+
+  const summary = [];
+  if (newFiles.length > 0) summary.push(`${newFiles.length} new`);
+  if (modifiedFiles.length > 0) summary.push(`${modifiedFiles.length} modified`);
+  info(`${summary.join(", ")} file${changes.length === 1 ? "" : "s"} to pull`);
+  console.log("");
+
+  if (dryRun) {
+    info(`${dim("Dry run — no files were written.")}`);
+    console.log("");
+    return;
+  }
+
+  // Confirm
+  if (!force) {
+    const confirmed = await confirm("Pull these changes?");
+    if (!confirmed) {
+      console.log("  Cancelled.");
+      process.exit(0);
+    }
+    console.log("");
+  }
+
+  // Write files
+  let written = 0;
+  for (const c of changes) {
+    await c.write();
+    written++;
+    ok(`${cyan(c.file)}`);
+  }
+
+  // Update sync state
+  updateSyncState(projectDir, link, slug, data.version, data.updatedAt);
+
+  console.log("");
+  ok(
+    `Pulled ${bold(String(written))} file${written === 1 ? "" : "s"} from ${cyan(slug + ".htmlhost.co")}`
+  );
+  console.log("");
+}
+
+/**
+ * Update the .htmlhost sync state after a pull or deploy.
+ */
+function updateSyncState(projectDir, existingLink, slug, version, updatedAt) {
+  const link = existingLink || {};
+  link.sync = {
+    version,
+    updatedAt,
+    pulledAt: new Date().toISOString(),
+  };
+  writeLink(projectDir, link);
+}
+
+/**
+ * Check if the remote site has been modified since the last deploy/pull.
+ * Used by the deploy command for pre-deploy diff checking.
+ *
+ * Returns null if up-to-date, or the remote metadata if changes exist.
+ */
+export async function checkRemoteChanges(slug) {
+  try {
+    const data = await get(
+      `/api/sites/pull?slug=${encodeURIComponent(slug)}&meta=true`
+    );
+    return data;
+  } catch {
+    // Network error or auth issue — don't block deploy
+    return null;
+  }
+}
+
+/**
+ * Format relative time for display.
+ */
+function relTime(iso) {
+  const diff = Date.now() - new Date(iso).getTime();
+  if (diff < 0) return "just now";
+  const secs = Math.floor(diff / 1000);
+  if (secs < 60) return "just now";
+  const mins = Math.floor(secs / 60);
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}