@indigoai-us/hq-cli 5.12.1 → 5.12.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [5.12.2] — 2026-05-10
+
+### Added
+
+- **`hq sync pull --all`** — fan out across every company you're a member of
+  plus your personal vault into `<hq-root>` in one shot. Companies land at
+  `<hq-root>/companies/<slug>`; the personal vault syncs at `<hq-root>` itself.
+  Mirrors the orchestration `hq-sync-runner --companies --direction pull` does
+  but reachable from the CLI front-end. Used by the Outpost cloud-init to
+  prime `/home/ec2-user/hq` on first boot.
+
 ## [5.12.1] — 2026-05-09
 
 ### Fixed

package/dist/commands/cloud.d.ts

@@ -13,5 +13,62 @@
  *   hq sync status            — show local journal summary
  */
 import { Command } from "commander";
+import { type ConflictStrategy } from "@indigoai-us/hq-cloud";
+export interface PullAllVaultClient {
+    listMyMemberships(): Promise<Array<{
+        companyUid: string;
+    }>>;
+    listPersonEntities(): Promise<Array<{
+        uid: string;
+        type: string;
+        slug: string;
+        bucketName?: string;
+        createdAt: string;
+    }>>;
+    getEntity(uid: string): Promise<{
+        slug?: string;
+        name?: string;
+    } | null>;
+}
+export interface SyncCallOptions {
+    company: string;
+    hqRoot: string;
+    onConflict?: ConflictStrategy;
+    personalMode?: boolean;
+    journalSlug?: string;
+}
+export interface SyncCallResult {
+    filesDownloaded: number;
+    bytesDownloaded: number;
+    filesSkipped: number;
+    conflicts: number;
+    conflictPaths: string[];
+    aborted: boolean;
+}
+export interface PullAllDeps {
+    vaultClient: PullAllVaultClient;
+    sync: (options: SyncCallOptions) => Promise<SyncCallResult>;
+}
+export interface PullAllOptions {
+    hqRoot: string;
+    onConflict?: ConflictStrategy;
+}
+export interface PullAllRow {
+    slug: string;
+    result?: SyncCallResult;
+    error?: string;
+}
+export interface PullAllResult {
+    attempted: number;
+    filesDownloaded: number;
+    bytesDownloaded: number;
+    conflicts: number;
+    errors: Array<{
+        company: string;
+        message: string;
+    }>;
+    perCompany: PullAllRow[];
+}
+export declare function pullAll(options: PullAllOptions, deps: PullAllDeps): Promise<PullAllResult>;
 export declare function registerCloudCommands(program: Command): void;
 //# sourceMappingURL=cloud.d.ts.map

package/dist/commands/cloud.js

@@ -13,12 +13,86 @@
  *   hq sync status            — show local journal summary
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="213f074e-13c2-5b95-9519-813adf9adfa9")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e7f5f66e-78d5-5787-acb4-fe35424f69c9")}catch(e){}}();
 import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
-import { share, sync, readJournal, getJournalPath, loadCachedTokens, } from "@indigoai-us/hq-cloud";
+import { share, sync, readJournal, getJournalPath, loadCachedTokens, VaultClient, } from "@indigoai-us/hq-cloud";
 import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
+// Oldest-first by createdAt, ties broken by uid lexicographic — matches
+// `pickCanonicalPersonEntity` in @indigoai-us/hq-cloud so the CLI lands on
+// the same person bucket that `hq-sync-runner` picks.
+function pickCanonicalPerson(persons) {
+    const onlyPersons = persons.filter((e) => e.type === "person");
+    if (onlyPersons.length === 0)
+        return null;
+    return [...onlyPersons].sort((a, b) => {
+        if (a.createdAt !== b.createdAt)
+            return a.createdAt < b.createdAt ? -1 : 1;
+        return a.uid < b.uid ? -1 : 1;
+    })[0];
+}
+export async function pullAll(options, deps) {
+    const memberships = await deps.vaultClient.listMyMemberships();
+    const persons = await deps.vaultClient.listPersonEntities();
+    const plan = [];
+    for (const m of memberships) {
+        let slug = m.companyUid;
+        try {
+            const info = await deps.vaultClient.getEntity(m.companyUid);
+            if (info?.slug)
+                slug = info.slug;
+        }
+        catch {
+            // Best-effort — keep UID as the row label rather than aborting the run.
+        }
+        plan.push({
+            slug,
+            syncOptions: {
+                company: m.companyUid,
+                hqRoot: options.hqRoot,
+                ...(options.onConflict ? { onConflict: options.onConflict } : {}),
+            },
+        });
+    }
+    const personal = pickCanonicalPerson(persons);
+    if (personal) {
+        plan.push({
+            slug: "personal",
+            syncOptions: {
+                company: personal.uid,
+                hqRoot: options.hqRoot,
+                personalMode: true,
+                journalSlug: "personal",
+                ...(options.onConflict ? { onConflict: options.onConflict } : {}),
+            },
+        });
+    }
+    const result = {
+        attempted: 0,
+        filesDownloaded: 0,
+        bytesDownloaded: 0,
+        conflicts: 0,
+        errors: [],
+        perCompany: [],
+    };
+    for (const entry of plan) {
+        result.attempted += 1;
+        try {
+            const r = await deps.sync(entry.syncOptions);
+            result.filesDownloaded += r.filesDownloaded;
+            result.bytesDownloaded += r.bytesDownloaded;
+            result.conflicts += r.conflicts;
+            result.perCompany.push({ slug: entry.slug, result: r });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            result.errors.push({ company: entry.slug, message });
+            result.perCompany.push({ slug: entry.slug, error: message });
+        }
+    }
+    return result;
+}
 export function registerCloudCommands(program) {
     program
         .command("push")
@@ -143,7 +217,14 @@ export function registerCloudCommands(program) {
         .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
         .option("--company <slug>", "Company slug or UID (defaults to active company in .hq/config.json)")
         .option("--on-conflict <strategy>", "Conflict strategy: overwrite | keep | abort (omit for interactive)")
+        .option("--all", "Pull every company you are a member of plus your personal vault " +
+        "into <hq-root>. Companies land at <hq-root>/companies/<slug>; " +
+        "the personal vault syncs at <hq-root>. Ignores --company.")
         .action(async (options) => {
+        if (options.all) {
+            await runPullAll(options.hqRoot, options.onConflict);
+            return;
+        }
         try {
             console.log(chalk.bold("\nHQ Sync — Pull"));
             console.log(`  HQ root:  ${options.hqRoot}`);
@@ -211,6 +292,68 @@ export function registerCloudCommands(program) {
         }
     });
 }
+async function runPullAll(hqRoot, onConflict) {
+    console.log(chalk.bold("\nHQ Sync — Pull (all)"));
+    console.log(`  HQ root:  ${hqRoot}`);
+    console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
+    let result;
+    try {
+        const accessToken = await ensureCognitoToken();
+        const vaultConfig = buildVaultConfig(accessToken);
+        const realClient = new VaultClient(vaultConfig);
+        const adapter = {
+            listMyMemberships: () => realClient.listMyMemberships(),
+            listPersonEntities: () => realClient.entity.listByType("person"),
+            getEntity: async (uid) => {
+                try {
+                    return await realClient.entity.get(uid);
+                }
+                catch {
+                    return null;
+                }
+            },
+        };
+        result = await pullAll({ hqRoot, ...(onConflict ? { onConflict } : {}) }, {
+            vaultClient: adapter,
+            sync: (opts) => sync({
+                company: opts.company,
+                hqRoot: opts.hqRoot,
+                vaultConfig,
+                ...(opts.onConflict ? { onConflict: opts.onConflict } : {}),
+                ...(opts.personalMode !== undefined
+                    ? { personalMode: opts.personalMode }
+                    : {}),
+                ...(opts.journalSlug !== undefined
+                    ? { journalSlug: opts.journalSlug }
+                    : {}),
+            }),
+        });
+    }
+    catch (err) {
+        console.error(chalk.red("\n✗ Pull-all failed:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+    for (const row of result.perCompany) {
+        if (row.error) {
+            console.log(chalk.red(`  ✗ ${row.slug}: ${row.error}`));
+        }
+        else if (row.result) {
+            const r = row.result;
+            const status = r.aborted ? chalk.yellow("⚠") : chalk.green("✓");
+            console.log(`  ${status} ${row.slug}: ${r.filesDownloaded} file(s), ` +
+                `${formatBytes(r.bytesDownloaded)}, ` +
+                `${r.filesSkipped} skipped, ${r.conflicts} conflict(s)` +
+                (r.aborted ? " — aborted" : ""));
+        }
+    }
+    const errored = result.errors.length;
+    const summary = `\nPulled ${result.filesDownloaded} file(s) ` +
+        `(${formatBytes(result.bytesDownloaded)}) across ${result.attempted} ` +
+        `target(s); ${result.conflicts} conflict(s); ${errored} error(s)`;
+    console.log(errored > 0 ? chalk.yellow(summary) : chalk.green(summary));
+    if (errored > 0)
+        process.exit(1);
+}
 function formatBytes(bytes) {
     if (bytes === 0)
         return "0 B";
@@ -266,4 +409,4 @@ function resolveUploadAuthorFromCache() {
     }
 }
 //# sourceMappingURL=cloud.js.map
-//# debugId=213f074e-13c2-5b95-9519-813adf9adfa9
+//# debugId=e7f5f66e-78d5-5787-acb4-fe35424f69c9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.12.1",
+  "version": "5.12.2",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

package/src/commands/cloud.pull-all.test.ts

@@ -0,0 +1,327 @@
+/**
+ * Unit tests for `pullAll` — the orchestrator behind `hq sync pull --all`.
+ *
+ * Mirrors the dependency-injection layout used in `cloud-provision.test.ts`:
+ * the action handler in `cloud.ts` resolves a real `VaultClient` + `sync`,
+ * but `pullAll` itself takes them as deps so we can exercise the fanout
+ * logic without network or filesystem.
+ *
+ * Coverage:
+ *   1. Happy path — companies + personal both fan out.
+ *   2. Conflict strategy is forwarded to every sync() call.
+ *   3. Per-company errors don't abort the rest of the fanout.
+ *   4. No person entity → companies-only plan, no personal target.
+ *   5. Empty memberships AND no person entity → no sync calls, clean result.
+ *   6. Multiple person entities → canonical pick (oldest createdAt, uid tiebreak).
+ *   7. hqRoot is forwarded verbatim to every sync() call.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  pullAll,
+  type PullAllDeps,
+  type PullAllVaultClient,
+  type SyncCallOptions,
+  type SyncCallResult,
+} from "./cloud.js";
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+interface FakeMembership {
+  companyUid: string;
+}
+
+interface FakeEntity {
+  uid: string;
+  type: "person" | "company";
+  slug: string;
+  bucketName?: string;
+  createdAt: string;
+}
+
+function makeVaultClient(opts: {
+  memberships?: FakeMembership[];
+  persons?: FakeEntity[];
+  entitiesBySlug?: Record<string, { slug: string; name?: string }>;
+  failGetEntityFor?: Set<string>;
+}): PullAllVaultClient {
+  return {
+    listMyMemberships: vi
+      .fn<[], Promise<FakeMembership[]>>()
+      .mockResolvedValue(opts.memberships ?? []),
+    listPersonEntities: vi
+      .fn<[], Promise<FakeEntity[]>>()
+      .mockResolvedValue(opts.persons ?? []),
+    getEntity: vi
+      .fn<[string], Promise<{ slug?: string; name?: string } | null>>()
+      .mockImplementation(async (uid: string) => {
+        if (opts.failGetEntityFor?.has(uid)) {
+          throw new Error(`fake getEntity failure for ${uid}`);
+        }
+        return opts.entitiesBySlug?.[uid] ?? null;
+      }),
+  };
+}
+
+function makeSyncSpy(
+  perCallOverrides: Record<string, Partial<SyncCallResult> | Error> = {},
+): {
+  fn: PullAllDeps["sync"];
+  calls: SyncCallOptions[];
+} {
+  const calls: SyncCallOptions[] = [];
+  const fn: PullAllDeps["sync"] = vi
+    .fn<[SyncCallOptions], Promise<SyncCallResult>>()
+    .mockImplementation(async (options: SyncCallOptions) => {
+      calls.push(options);
+      const override = perCallOverrides[options.company];
+      if (override instanceof Error) {
+        throw override;
+      }
+      return {
+        filesDownloaded: 0,
+        bytesDownloaded: 0,
+        filesSkipped: 0,
+        conflicts: 0,
+        conflictPaths: [],
+        aborted: false,
+        ...override,
+      };
+    });
+  return { fn, calls };
+}
+
+// ── 1. Happy path ───────────────────────────────────────────────────────────
+
+describe("pullAll", () => {
+  it("syncs every membership plus the canonical person entity", async () => {
+    const vaultClient = makeVaultClient({
+      memberships: [
+        { companyUid: "cmp_acme" },
+        { companyUid: "cmp_globex" },
+      ],
+      persons: [
+        {
+          uid: "psn_alice",
+          type: "person",
+          slug: "alice",
+          bucketName: "hq-vault-psn-alice",
+          createdAt: "2026-01-01T00:00:00Z",
+        },
+      ],
+      entitiesBySlug: {
+        cmp_acme: { slug: "acme", name: "Acme" },
+        cmp_globex: { slug: "globex", name: "Globex" },
+      },
+    });
+    const sync = makeSyncSpy({
+      cmp_acme: { filesDownloaded: 3, bytesDownloaded: 300 },
+      cmp_globex: { filesDownloaded: 1, bytesDownloaded: 50 },
+      psn_alice: { filesDownloaded: 7, bytesDownloaded: 700 },
+    });
+
+    const result = await pullAll(
+      { hqRoot: "/tmp/hq", onConflict: "abort" },
+      { vaultClient, sync: sync.fn },
+    );
+
+    expect(sync.calls).toHaveLength(3);
+    expect(sync.calls[0]).toMatchObject({
+      company: "cmp_acme",
+      hqRoot: "/tmp/hq",
+      onConflict: "abort",
+    });
+    expect(sync.calls[1]).toMatchObject({ company: "cmp_globex" });
+    expect(sync.calls[2]).toMatchObject({
+      company: "psn_alice",
+      personalMode: true,
+      journalSlug: "personal",
+    });
+
+    expect(result.attempted).toBe(3);
+    expect(result.filesDownloaded).toBe(11);
+    expect(result.bytesDownloaded).toBe(1050);
+    expect(result.errors).toEqual([]);
+    expect(result.perCompany.map((row) => row.slug)).toEqual([
+      "acme",
+      "globex",
+      "personal",
+    ]);
+  });
+
+  // ── 2. Conflict strategy passthrough ──────────────────────────────────────
+
+  it("forwards --on-conflict to every sync() call", async () => {
+    const vaultClient = makeVaultClient({
+      memberships: [{ companyUid: "cmp_acme" }],
+      persons: [
+        {
+          uid: "psn_alice",
+          type: "person",
+          slug: "alice",
+          createdAt: "2026-01-01T00:00:00Z",
+        },
+      ],
+    });
+    const sync = makeSyncSpy();
+
+    await pullAll(
+      { hqRoot: "/tmp/hq", onConflict: "overwrite" },
+      { vaultClient, sync: sync.fn },
+    );
+
+    for (const call of sync.calls) {
+      expect(call.onConflict).toBe("overwrite");
+    }
+  });
+
+  // ── 3. Per-company error isolation ────────────────────────────────────────
+
+  it("continues past a per-company sync failure and reports it in errors[]", async () => {
+    const vaultClient = makeVaultClient({
+      memberships: [
+        { companyUid: "cmp_acme" },
+        { companyUid: "cmp_globex" },
+      ],
+      persons: [
+        {
+          uid: "psn_alice",
+          type: "person",
+          slug: "alice",
+          createdAt: "2026-01-01T00:00:00Z",
+        },
+      ],
+      entitiesBySlug: {
+        cmp_acme: { slug: "acme" },
+        cmp_globex: { slug: "globex" },
+      },
+    });
+    const sync = makeSyncSpy({
+      cmp_globex: new Error("STS denied"),
+    });
+
+    const result = await pullAll(
+      { hqRoot: "/tmp/hq" },
+      { vaultClient, sync: sync.fn },
+    );
+
+    expect(sync.calls.map((c) => c.company)).toEqual([
+      "cmp_acme",
+      "cmp_globex",
+      "psn_alice",
+    ]);
+    expect(result.attempted).toBe(3);
+    expect(result.errors).toEqual([
+      { company: "globex", message: "STS denied" },
+    ]);
+    const globexRow = result.perCompany.find((r) => r.slug === "globex");
+    expect(globexRow?.error).toBe("STS denied");
+    expect(globexRow?.result).toBeUndefined();
+  });
+
+  // ── 4. No person entity ────────────────────────────────────────────────────
+
+  it("omits the personal target when listPersonEntities returns []", async () => {
+    const vaultClient = makeVaultClient({
+      memberships: [{ companyUid: "cmp_acme" }],
+      persons: [],
+      entitiesBySlug: { cmp_acme: { slug: "acme" } },
+    });
+    const sync = makeSyncSpy();
+
+    const result = await pullAll(
+      { hqRoot: "/tmp/hq" },
+      { vaultClient, sync: sync.fn },
+    );
+
+    expect(sync.calls).toHaveLength(1);
+    expect(sync.calls[0].company).toBe("cmp_acme");
+    expect(sync.calls[0].personalMode).toBeUndefined();
+    expect(result.perCompany.map((r) => r.slug)).toEqual(["acme"]);
+  });
+
+  // ── 5. No memberships and no person entity ────────────────────────────────
+
+  it("returns cleanly with zero attempts when there is nothing to sync", async () => {
+    const vaultClient = makeVaultClient({});
+    const sync = makeSyncSpy();
+
+    const result = await pullAll(
+      { hqRoot: "/tmp/hq" },
+      { vaultClient, sync: sync.fn },
+    );
+
+    expect(sync.calls).toEqual([]);
+    expect(result).toEqual({
+      attempted: 0,
+      filesDownloaded: 0,
+      bytesDownloaded: 0,
+      conflicts: 0,
+      errors: [],
+      perCompany: [],
+    });
+  });
+
+  // ── 6. Canonical-person tiebreak ──────────────────────────────────────────
+
+  it("picks the oldest person entity, breaking ties by uid", async () => {
+    const vaultClient = makeVaultClient({
+      memberships: [],
+      persons: [
+        {
+          uid: "psn_zzz",
+          type: "person",
+          slug: "alice-zzz",
+          createdAt: "2026-01-01T00:00:00Z",
+        },
+        {
+          uid: "psn_aaa",
+          type: "person",
+          slug: "alice-aaa",
+          createdAt: "2026-01-01T00:00:00Z",
+        },
+        {
+          uid: "psn_old",
+          type: "person",
+          slug: "alice-old",
+          createdAt: "2025-06-01T00:00:00Z",
+        },
+      ],
+    });
+    const sync = makeSyncSpy();
+
+    await pullAll({ hqRoot: "/tmp/hq" }, { vaultClient, sync: sync.fn });
+
+    expect(sync.calls).toHaveLength(1);
+    expect(sync.calls[0].company).toBe("psn_old");
+    expect(sync.calls[0].personalMode).toBe(true);
+    expect(sync.calls[0].journalSlug).toBe("personal");
+  });
+
+  // ── 7. hqRoot passthrough ─────────────────────────────────────────────────
+
+  it("forwards hqRoot verbatim to every sync() call", async () => {
+    const vaultClient = makeVaultClient({
+      memberships: [{ companyUid: "cmp_acme" }],
+      persons: [
+        {
+          uid: "psn_alice",
+          type: "person",
+          slug: "alice",
+          createdAt: "2026-01-01T00:00:00Z",
+        },
+      ],
+    });
+    const sync = makeSyncSpy();
+
+    await pullAll(
+      { hqRoot: "/Users/me/scratch/hq" },
+      { vaultClient, sync: sync.fn },
+    );
+
+    for (const call of sync.calls) {
+      expect(call.hqRoot).toBe("/Users/me/scratch/hq");
+    }
+  });
+});

package/src/commands/cloud.ts

@@ -24,6 +24,7 @@ import {
   readJournal,
   getJournalPath,
   loadCachedTokens,
+  VaultClient,
   type ConflictStrategy,
   type EntityContext,
   type SyncProgressEvent,
@@ -41,6 +42,157 @@ interface CommonSyncOptions {
   company?: string;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// `hq sync pull --all` orchestrator
+//
+// Mirrors the fanout that `hq-sync-runner --companies --direction pull` does
+// in the menubar app: list every membership, append the canonical person
+// entity, sync each target into <hq-root>. Extracted as a pure function with
+// injectable deps so cloud.pull-all.test.ts can drive it without network.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface PullAllVaultClient {
+  listMyMemberships(): Promise<Array<{ companyUid: string }>>;
+  listPersonEntities(): Promise<
+    Array<{
+      uid: string;
+      type: string;
+      slug: string;
+      bucketName?: string;
+      createdAt: string;
+    }>
+  >;
+  getEntity(uid: string): Promise<{ slug?: string; name?: string } | null>;
+}
+
+export interface SyncCallOptions {
+  company: string;
+  hqRoot: string;
+  onConflict?: ConflictStrategy;
+  personalMode?: boolean;
+  journalSlug?: string;
+}
+
+export interface SyncCallResult {
+  filesDownloaded: number;
+  bytesDownloaded: number;
+  filesSkipped: number;
+  conflicts: number;
+  conflictPaths: string[];
+  aborted: boolean;
+}
+
+export interface PullAllDeps {
+  vaultClient: PullAllVaultClient;
+  sync: (options: SyncCallOptions) => Promise<SyncCallResult>;
+}
+
+export interface PullAllOptions {
+  hqRoot: string;
+  onConflict?: ConflictStrategy;
+}
+
+export interface PullAllRow {
+  slug: string;
+  result?: SyncCallResult;
+  error?: string;
+}
+
+export interface PullAllResult {
+  attempted: number;
+  filesDownloaded: number;
+  bytesDownloaded: number;
+  conflicts: number;
+  errors: Array<{ company: string; message: string }>;
+  perCompany: PullAllRow[];
+}
+
+interface PlanEntry {
+  slug: string;
+  syncOptions: SyncCallOptions;
+}
+
+// Oldest-first by createdAt, ties broken by uid lexicographic — matches
+// `pickCanonicalPersonEntity` in @indigoai-us/hq-cloud so the CLI lands on
+// the same person bucket that `hq-sync-runner` picks.
+function pickCanonicalPerson<
+  E extends { uid: string; type: string; createdAt: string },
+>(persons: E[]): E | null {
+  const onlyPersons = persons.filter((e) => e.type === "person");
+  if (onlyPersons.length === 0) return null;
+  return [...onlyPersons].sort((a, b) => {
+    if (a.createdAt !== b.createdAt) return a.createdAt < b.createdAt ? -1 : 1;
+    return a.uid < b.uid ? -1 : 1;
+  })[0];
+}
+
+export async function pullAll(
+  options: PullAllOptions,
+  deps: PullAllDeps,
+): Promise<PullAllResult> {
+  const memberships = await deps.vaultClient.listMyMemberships();
+  const persons = await deps.vaultClient.listPersonEntities();
+
+  const plan: PlanEntry[] = [];
+  for (const m of memberships) {
+    let slug = m.companyUid;
+    try {
+      const info = await deps.vaultClient.getEntity(m.companyUid);
+      if (info?.slug) slug = info.slug;
+    } catch {
+      // Best-effort — keep UID as the row label rather than aborting the run.
+    }
+    plan.push({
+      slug,
+      syncOptions: {
+        company: m.companyUid,
+        hqRoot: options.hqRoot,
+        ...(options.onConflict ? { onConflict: options.onConflict } : {}),
+      },
+    });
+  }
+
+  const personal = pickCanonicalPerson(persons);
+  if (personal) {
+    plan.push({
+      slug: "personal",
+      syncOptions: {
+        company: personal.uid,
+        hqRoot: options.hqRoot,
+        personalMode: true,
+        journalSlug: "personal",
+        ...(options.onConflict ? { onConflict: options.onConflict } : {}),
+      },
+    });
+  }
+
+  const result: PullAllResult = {
+    attempted: 0,
+    filesDownloaded: 0,
+    bytesDownloaded: 0,
+    conflicts: 0,
+    errors: [],
+    perCompany: [],
+  };
+
+  for (const entry of plan) {
+    result.attempted += 1;
+    try {
+      const r = await deps.sync(entry.syncOptions);
+      result.filesDownloaded += r.filesDownloaded;
+      result.bytesDownloaded += r.bytesDownloaded;
+      result.conflicts += r.conflicts;
+      result.perCompany.push({ slug: entry.slug, result: r });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      result.errors.push({ company: entry.slug, message });
+      result.perCompany.push({ slug: entry.slug, error: message });
+    }
+  }
+
+  return result;
+}
+
 export function registerCloudCommands(program: Command): void {
   program
     .command("push")
@@ -228,12 +380,23 @@ export function registerCloudCommands(program: Command): void {
       "--on-conflict <strategy>",
       "Conflict strategy: overwrite | keep | abort (omit for interactive)",
     )
+    .option(
+      "--all",
+      "Pull every company you are a member of plus your personal vault " +
+        "into <hq-root>. Companies land at <hq-root>/companies/<slug>; " +
+        "the personal vault syncs at <hq-root>. Ignores --company.",
+    )
     .action(
       async (
         options: CommonSyncOptions & {
           onConflict?: ConflictStrategy;
+          all?: boolean;
         },
       ) => {
+        if (options.all) {
+          await runPullAll(options.hqRoot, options.onConflict);
+          return;
+        }
         try {
           console.log(chalk.bold("\nHQ Sync — Pull"));
           console.log(`  HQ root:  ${options.hqRoot}`);
@@ -328,6 +491,83 @@ export function registerCloudCommands(program: Command): void {
     });
 }
 
+async function runPullAll(
+  hqRoot: string,
+  onConflict?: ConflictStrategy,
+): Promise<void> {
+  console.log(chalk.bold("\nHQ Sync — Pull (all)"));
+  console.log(`  HQ root:  ${hqRoot}`);
+  console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
+
+  let result: PullAllResult;
+  try {
+    const accessToken = await ensureCognitoToken();
+    const vaultConfig = buildVaultConfig(accessToken);
+    const realClient = new VaultClient(vaultConfig);
+
+    const adapter: PullAllVaultClient = {
+      listMyMemberships: () => realClient.listMyMemberships(),
+      listPersonEntities: () => realClient.entity.listByType("person"),
+      getEntity: async (uid: string) => {
+        try {
+          return await realClient.entity.get(uid);
+        } catch {
+          return null;
+        }
+      },
+    };
+
+    result = await pullAll(
+      { hqRoot, ...(onConflict ? { onConflict } : {}) },
+      {
+        vaultClient: adapter,
+        sync: (opts) =>
+          sync({
+            company: opts.company,
+            hqRoot: opts.hqRoot,
+            vaultConfig,
+            ...(opts.onConflict ? { onConflict: opts.onConflict } : {}),
+            ...(opts.personalMode !== undefined
+              ? { personalMode: opts.personalMode }
+              : {}),
+            ...(opts.journalSlug !== undefined
+              ? { journalSlug: opts.journalSlug }
+              : {}),
+          }),
+      },
+    );
+  } catch (err) {
+    console.error(
+      chalk.red("\n✗ Pull-all failed:"),
+      err instanceof Error ? err.message : String(err),
+    );
+    process.exit(1);
+  }
+
+  for (const row of result.perCompany) {
+    if (row.error) {
+      console.log(chalk.red(`  ✗ ${row.slug}: ${row.error}`));
+    } else if (row.result) {
+      const r = row.result;
+      const status = r.aborted ? chalk.yellow("⚠") : chalk.green("✓");
+      console.log(
+        `  ${status} ${row.slug}: ${r.filesDownloaded} file(s), ` +
+          `${formatBytes(r.bytesDownloaded)}, ` +
+          `${r.filesSkipped} skipped, ${r.conflicts} conflict(s)` +
+          (r.aborted ? " — aborted" : ""),
+      );
+    }
+  }
+
+  const errored = result.errors.length;
+  const summary =
+    `\nPulled ${result.filesDownloaded} file(s) ` +
+    `(${formatBytes(result.bytesDownloaded)}) across ${result.attempted} ` +
+    `target(s); ${result.conflicts} conflict(s); ${errored} error(s)`;
+  console.log(errored > 0 ? chalk.yellow(summary) : chalk.green(summary));
+  if (errored > 0) process.exit(1);
+}
+
 function formatBytes(bytes: number): string {
   if (bytes === 0) return "0 B";
   const units = ["B", "KB", "MB", "GB"];