@indigoai-us/hq-cli 5.6.3 → 5.8.3

package/dist/commands/_patterns.d.ts

@@ -1,3 +1,5 @@
 export declare const SECRET_NAME_PATTERN: RegExp;
 export declare const GROUP_ID_PATTERN: RegExp;
+export declare const EMAIL_PATTERN: RegExp;
+export declare function normalizeFilePrefix(prefix: string): string;
 //# sourceMappingURL=_patterns.d.ts.map

package/dist/commands/_patterns.js

@@ -1,6 +1,13 @@
 
-!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]="61b178c5-2bd1-5503-bbee-ecb98a9d72f5")}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]="0d9c591b-d54a-52b4-85c3-32a9030953ca")}catch(e){}}();
 export const SECRET_NAME_PATTERN = /^[A-Z][A-Z0-9_]*(?:\/[A-Z][A-Z0-9_]+)*$/;
 export const GROUP_ID_PATTERN = /^grp_[A-Za-z0-9_-]+$/;
+export const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
+export function normalizeFilePrefix(prefix) {
+    if (prefix.endsWith("/")) {
+        return prefix + "*";
+    }
+    return prefix;
+}
 //# sourceMappingURL=_patterns.js.map
-//# debugId=61b178c5-2bd1-5503-bbee-ecb98a9d72f5
+//# debugId=0d9c591b-d54a-52b4-85c3-32a9030953ca

package/dist/commands/cloud.js

@@ -13,7 +13,7 @@
  *   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]="a3524c87-f874-56f4-92b3-9c33467b4f95")}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]="5ddbce6a-fdde-506e-8cdd-2e5b0ad20fff")}catch(e){}}();
 import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
@@ -28,30 +28,104 @@ export function registerCloudCommands(program) {
         .option("--company <slug>", "Company slug or UID (defaults to active company in .hq/config.json)")
         .option("--message <msg>", "Optional message attached to journal entries for these uploads")
         .option("--on-conflict <strategy>", "Conflict strategy: overwrite | keep | abort (omit for interactive)")
+        .option("--creds-from-stdin", "Read a pre-vended EntityContext as JSON from stdin instead of vending " +
+        "via the cached Cognito session. Use when the caller (e.g. AppBar HQ " +
+        "Sync) has its own STS pipeline (`/sts/vend-child` with task scope) " +
+        "and just needs share()'s upload mechanics. The caller is responsible " +
+        "for vending credentials with enough TTL for the run.")
+        .option("--json", "Emit each share()-level event as a JSON Lines record on stderr (one " +
+        "JSON object per line) instead of human-readable console output. A " +
+        "synthetic `{type:\"complete\",...}` line is appended at the end with " +
+        "the final ShareResult. Subprocess callers parse these to render their " +
+        "own UI (e.g. AppBar Tauri events).")
         .action(async (paths, options) => {
+        const jsonMode = options.json === true;
+        // Suppress the human banner/result output in JSON mode — the parent
+        // process renders its own UI from the stderr ndjson stream.
+        const log = (msg) => {
+            if (!jsonMode)
+                console.log(msg);
+        };
+        const emitJson = (event) => {
+            process.stderr.write(JSON.stringify(event) + "\n");
+        };
         try {
             const targetPaths = paths && paths.length > 0 ? paths : [process.cwd()];
-            console.log(chalk.bold("\nHQ Sync — Push"));
-            console.log(`  HQ root:  ${options.hqRoot}`);
-            console.log(`  Company:  ${options.company ?? "(from .hq/config.json)"}`);
-            console.log(`  Paths:    ${targetPaths.join(", ")}\n`);
-            const accessToken = await ensureCognitoToken();
+            log(chalk.bold("\nHQ Sync — Push"));
+            log(`  HQ root:  ${options.hqRoot}`);
+            log(`  Company:  ${options.company ?? "(from .hq/config.json or stdin)"}`);
+            log(`  Paths:    ${targetPaths.join(", ")}\n`);
+            // Resolve credentials. Two paths:
+            //   1. --creds-from-stdin: parse JSON EntityContext from stdin (the
+            //      AppBar shell-out contract — vend-child upstream, pipe in here).
+            //   2. default: vend via cached Cognito session (the human CLI path).
+            let entityContext;
+            let vaultConfig;
+            if (options.credsFromStdin) {
+                if (process.stdin.isTTY) {
+                    throw new Error("--creds-from-stdin requires JSON on stdin, but stdin is a " +
+                        "TTY. Pipe the EntityContext JSON via subprocess stdin " +
+                        "(e.g. `echo '{...}' | hq sync push --creds-from-stdin ...`).");
+                }
+                const raw = await readAllStdin();
+                try {
+                    entityContext = JSON.parse(raw);
+                }
+                catch (e) {
+                    throw new Error(`--creds-from-stdin: failed to parse stdin as JSON: ${e instanceof Error ? e.message : String(e)}`);
+                }
+            }
+            else {
+                const accessToken = await ensureCognitoToken();
+                vaultConfig = buildVaultConfig(accessToken);
+            }
+            // In JSON mode, forward every share() event verbatim to stderr as
+            // ndjson. In human mode, share()'s defaultConsoleLogger handles the
+            // rendering (no onEvent → falls through to stdout/stderr printing).
+            const onEvent = jsonMode
+                ? (event) => emitJson(event)
+                : undefined;
             const result = await share({
                 paths: targetPaths,
                 company: options.company,
                 message: options.message,
                 onConflict: options.onConflict,
-                vaultConfig: buildVaultConfig(accessToken),
+                vaultConfig,
+                entityContext,
                 hqRoot: options.hqRoot,
+                onEvent,
             });
+            if (jsonMode) {
+                // Synthetic terminal event so subprocess consumers can read final
+                // counts without summing per-file events. Distinguished from
+                // SyncProgressEvent by `type:"complete"` (not in the share()
+                // event schema — added at the CLI seam).
+                emitJson({
+                    type: "complete",
+                    filesUploaded: result.filesUploaded,
+                    bytesUploaded: result.bytesUploaded,
+                    filesSkipped: result.filesSkipped,
+                    conflictPaths: result.conflictPaths,
+                    aborted: result.aborted,
+                });
+            }
             if (result.aborted) {
-                console.log(chalk.yellow(`\n⚠ Push aborted (${result.filesUploaded} uploaded, ${result.filesSkipped} skipped)`));
+                log(chalk.yellow(`\n⚠ Push aborted (${result.filesUploaded} uploaded, ${result.filesSkipped} skipped)`));
                 process.exit(1);
             }
-            console.log(chalk.green(`\n✓ Pushed ${result.filesUploaded} file(s) (${formatBytes(result.bytesUploaded)}, ${result.filesSkipped} skipped)`));
+            log(chalk.green(`\n✓ Pushed ${result.filesUploaded} file(s) (${formatBytes(result.bytesUploaded)}, ${result.filesSkipped} skipped)`));
         }
         catch (err) {
-            console.error(chalk.red("\n✗ Push failed:"), err instanceof Error ? err.message : String(err));
+            const message = err instanceof Error ? err.message : String(err);
+            if (jsonMode) {
+                // In JSON mode, the parent process is parsing stderr for ndjson —
+                // human-formatted error lines would corrupt the stream. Emit a
+                // structured `fatal` event instead and let the parent surface it.
+                emitJson({ type: "fatal", message });
+            }
+            else {
+                console.error(chalk.red("\n✗ Push failed:"), message);
+            }
             process.exit(1);
         }
     });
@@ -137,5 +211,20 @@ function formatBytes(bytes) {
     const value = bytes / Math.pow(1024, exponent);
     return `${value.toFixed(value >= 100 || exponent === 0 ? 0 : 1)} ${units[exponent]}`;
 }
+/**
+ * Read all of stdin as a UTF-8 string. Used by `--creds-from-stdin` to
+ * receive a JSON-serialized EntityContext from the parent process (e.g.
+ * AppBar HQ Sync). Returns the empty string when stdin closes immediately.
+ *
+ * Caller is expected to detect TTY first — this function will block forever
+ * waiting for stdin to close if invoked interactively.
+ */
+async function readAllStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
 //# sourceMappingURL=cloud.js.map
-//# debugId=a3524c87-f874-56f4-92b3-9c33467b4f95
+//# debugId=5ddbce6a-fdde-506e-8cdd-2e5b0ad20fff

package/dist/commands/files.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function registerFilesCommand(program: Command): void;
+//# sourceMappingURL=files.d.ts.map

package/dist/commands/files.js

@@ -0,0 +1,206 @@
+
+!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]="5f7a9620-b2ba-5186-980c-76df147440f0")}catch(e){}}();
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch, getCompanyUid } from "./secrets.js";
+import { GROUP_ID_PATTERN, EMAIL_PATTERN, normalizeFilePrefix } from "./_patterns.js";
+export function registerFilesCommand(program) {
+    const files = program
+        .command("files")
+        .description("Manage file access controls in HQ vault")
+        .option("--company <slug>", "Company slug (resolves to companyUid)");
+    files
+        .command("share <prefix>")
+        .description("Share a file prefix with a person or group")
+        .requiredOption("--with <principal>", "Email address or group id to share with")
+        .requiredOption("--permission <level>", "Permission level: read | write")
+        .action(async (prefix, opts) => {
+        try {
+            const canonicalPrefix = normalizeFilePrefix(prefix);
+            if (!["read", "write"].includes(opts.permission)) {
+                console.error(chalk.red(`Invalid permission '${opts.permission}': must be one of read, write`));
+                process.exit(1);
+            }
+            const principal = opts.with;
+            const isEmail = EMAIL_PATTERN.test(principal);
+            const isGroup = GROUP_ID_PATTERN.test(principal);
+            if (!isEmail && !isGroup) {
+                console.error(chalk.red(`Invalid principal '${principal}': must be an email address or a group id matching grp_<alphanumeric>`));
+                process.exit(1);
+            }
+            const granteeType = isEmail ? "email" : "group";
+            const granteeId = isEmail ? principal.trim().toLowerCase() : principal;
+            const token = await ensureCognitoToken();
+            const companySlug = files.opts().company;
+            const companyUid = await getCompanyUid(token, companySlug);
+            const res = await vaultApiFetch({
+                token,
+                path: `/files/${encodeURIComponent(companyUid)}/acl/grant`,
+                method: "POST",
+                body: { prefix: canonicalPrefix, granteeType, granteeId, permission: opts.permission },
+            });
+            if (!res.ok) {
+                const body = await res.json().catch(() => ({}));
+                if (res.status === 401) {
+                    console.error(chalk.red("Not authenticated — please run `hq login`"));
+                }
+                else if (res.status === 403) {
+                    console.error(chalk.red("Not authorized to share this file prefix"));
+                }
+                else if (res.status === 404) {
+                    console.error(chalk.red("ACL record not found — the prefix may not have an ACL yet"));
+                }
+                else if (res.status === 409) {
+                    console.error(chalk.red("Concurrent modification — please retry"));
+                }
+                else if (res.status >= 500) {
+                    console.error(chalk.red(`Server error: ${body.error ?? res.statusText}`));
+                }
+                else {
+                    console.error(chalk.red(body.message ?? body.error ?? "Invalid request"));
+                }
+                process.exit(1);
+            }
+            const data = await res.json();
+            const printedPrefix = data.acl?.prefix ?? canonicalPrefix;
+            console.log(chalk.green(`Granted ${opts.permission} on ${printedPrefix} to ${granteeId}`));
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    files
+        .command("unshare <prefix>")
+        .description("Remove a file access grant")
+        .requiredOption("--with <principal>", "Email address or group id to remove")
+        .action(async (prefix, opts) => {
+        try {
+            const canonicalPrefix = normalizeFilePrefix(prefix);
+            const principal = opts.with;
+            const isEmail = EMAIL_PATTERN.test(principal);
+            const isGroup = GROUP_ID_PATTERN.test(principal);
+            if (!isEmail && !isGroup) {
+                console.error(chalk.red(`Invalid principal '${principal}': must be an email address or a group id matching grp_<alphanumeric>`));
+                process.exit(1);
+            }
+            const granteeType = isEmail ? "email" : "group";
+            const granteeId = isEmail ? principal.trim().toLowerCase() : principal;
+            const token = await ensureCognitoToken();
+            const companySlug = files.opts().company;
+            const companyUid = await getCompanyUid(token, companySlug);
+            const res = await vaultApiFetch({
+                token,
+                path: `/files/${encodeURIComponent(companyUid)}/acl/revoke`,
+                method: "POST",
+                body: { prefix: canonicalPrefix, granteeType, granteeId },
+            });
+            if (!res.ok) {
+                const body = await res.json().catch(() => ({}));
+                if (res.status === 401) {
+                    console.error(chalk.red("Not authenticated — please run `hq login`"));
+                }
+                else if (res.status === 403) {
+                    console.error(chalk.red("Not authorized to modify this file prefix's ACL"));
+                }
+                else if (res.status === 404) {
+                    console.log(chalk.green(`Grant already absent for '${canonicalPrefix}' / ${granteeId}`));
+                    return;
+                }
+                else if (res.status >= 500) {
+                    console.error(chalk.red(`Server error: ${body.error ?? res.statusText}`));
+                }
+                else {
+                    console.error(chalk.red(body.message ?? body.error ?? "Invalid request"));
+                }
+                process.exit(1);
+            }
+            console.log(chalk.green(`Removed grant for ${granteeId} on '${canonicalPrefix}'`));
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    files
+        .command("acl <prefix>")
+        .description("Show the ACL (access control list) for a file prefix")
+        .action(async (prefix) => {
+        try {
+            const canonicalPrefix = normalizeFilePrefix(prefix);
+            const token = await ensureCognitoToken();
+            const companySlug = files.opts().company;
+            const companyUid = await getCompanyUid(token, companySlug);
+            const res = await vaultApiFetch({
+                token,
+                path: `/files/${encodeURIComponent(companyUid)}/acl`,
+                query: { prefix: canonicalPrefix },
+            });
+            if (!res.ok) {
+                const body = await res.json().catch(() => ({}));
+                if (res.status === 401) {
+                    console.error(chalk.red("Not authenticated — please run `hq login`"));
+                }
+                else if (res.status === 403) {
+                    console.error(chalk.red("Not authorized to view this file prefix's ACL"));
+                }
+                else if (res.status === 404) {
+                    console.error(chalk.red(`No ACL record exists for '${canonicalPrefix}'`));
+                }
+                else if (res.status >= 500) {
+                    console.error(chalk.red(`Server error: ${body.error ?? res.statusText}`));
+                }
+                else {
+                    console.error(chalk.red(body.message ?? body.error ?? "Invalid request"));
+                }
+                process.exit(1);
+            }
+            const data = await res.json();
+            const acl = data.acl;
+            const aclStatus = acl.open ? "open" : "restricted";
+            console.log(chalk.green(`ACL for ${acl.prefix} (${aclStatus})`));
+            console.log(`Creator: ${acl.creatorUid}`);
+            if (acl.effectivePermission) {
+                console.log(`Your effective permission: ${acl.effectivePermission}`);
+            }
+            if (acl.entries.length === 0) {
+                if (acl.open) {
+                    console.log(chalk.gray("Open ACL — all active members have read access."));
+                }
+                else {
+                    console.log(chalk.gray("No explicit grants — only creator has access."));
+                }
+                return;
+            }
+            console.log("Entries:");
+            const TYPE_W = Math.max(4, ...acl.entries.map((e) => e.granteeType.length));
+            const GRANTEE_W = Math.max(7, ...acl.entries.map((e) => e.granteeId.length));
+            const PERM_W = Math.max(10, ...acl.entries.map((e) => e.permission.length));
+            const BY_W = Math.max(10, ...acl.entries.map((e) => e.grantedBy.length));
+            const tableHeader = [
+                "TYPE".padEnd(TYPE_W),
+                "GRANTEE".padEnd(GRANTEE_W),
+                "PERMISSION".padEnd(PERM_W),
+                "GRANTED_BY".padEnd(BY_W),
+                "GRANTED_AT",
+            ].join("  ");
+            console.log(chalk.bold(tableHeader));
+            for (const e of acl.entries) {
+                const grantedAt = e.grantedAt.slice(0, 10);
+                console.log([
+                    e.granteeType.padEnd(TYPE_W),
+                    e.granteeId.padEnd(GRANTEE_W),
+                    e.permission.padEnd(PERM_W),
+                    e.grantedBy.padEnd(BY_W),
+                    grantedAt,
+                ].join("  "));
+            }
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=files.js.map
+//# debugId=5f7a9620-b2ba-5186-980c-76df147440f0

package/dist/index.js

@@ -3,7 +3,7 @@
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
 
-!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]="8abd3fa1-9f1a-53b3-9d1c-cf764db1f670")}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]="79222b07-0f20-582f-962f-6bc13b8c1c88")}catch(e){}}();
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -24,12 +24,13 @@ import { registerTeamSyncCommand } from "./commands/team-sync.js";
 import { registerAuthCommands } from "./commands/auth.js";
 import { registerSecretsCommand } from "./commands/secrets.js";
 import { registerGroupsCommand } from "./commands/groups.js";
+import { registerFilesCommand } from "./commands/files.js";
 initSentry();
 const program = new Command();
 program
     .name("hq")
     .description("HQ management CLI — modules, packages, and cloud sync")
-    .version("5.5.0");
+    .version("5.8.3");
 // Module management subcommand group
 const modulesCmd = program
     .command("modules")
@@ -73,6 +74,8 @@ registerAuthCommands(program);
 registerSecretsCommand(program);
 // Groups management (subcommand group — hq groups create|delete|add|remove|list|members)
 registerGroupsCommand(program);
+// Files ACL management (subcommand group — hq files share|unshare|acl)
+registerFilesCommand(program);
 // Onboarding (top-level — Cognito + vault-service provisioning)
 registerOnboardCommand(program);
 (async () => {
@@ -88,4 +91,4 @@ registerOnboardCommand(program);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=8abd3fa1-9f1a-53b3-9d1c-cf764db1f670
+//# debugId=79222b07-0f20-582f-962f-6bc13b8c1c88

package/dist/utils/cognito-session.js

@@ -19,7 +19,7 @@
  *   HQ_VAULT_API_URL           — vault-service API Gateway URL
  */
 
-!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]="147a783f-029d-547f-ba36-a1dbf8ed0f65")}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]="71d8f748-f249-50df-aa1f-eae381ea608d")}catch(e){}}();
 import * as os from "os";
 import * as path from "path";
 import chalk from "chalk";
@@ -40,8 +40,7 @@ export const DEFAULT_COGNITO = {
         ? process.env.HQ_COGNITO_IDENTITY_PROVIDER || undefined
         : "Google",
 };
-export const DEFAULT_VAULT_API_URL = process.env.HQ_VAULT_API_URL ??
-    "https://4nfy67z28h.execute-api.us-east-1.amazonaws.com";
+export const DEFAULT_VAULT_API_URL = process.env.HQ_VAULT_API_URL ?? "https://hqapi.getindigo.ai";
 export const DEFAULT_HQ_ROOT = path.join(os.homedir(), "hq");
 /**
  * Return a non-expired Cognito access token, refreshing or browser-logging-in
@@ -109,4 +108,4 @@ export async function refreshCachedSession() {
     }
 }
 //# sourceMappingURL=cognito-session.js.map
-//# debugId=147a783f-029d-547f-ba36-a1dbf8ed0f65
+//# debugId=71d8f748-f249-50df-aa1f-eae381ea608d

package/package.json

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

package/src/commands/_patterns.ts

@@ -1,2 +1,10 @@
 export const SECRET_NAME_PATTERN = /^[A-Z][A-Z0-9_]*(?:\/[A-Z][A-Z0-9_]+)*$/;
 export const GROUP_ID_PATTERN = /^grp_[A-Za-z0-9_-]+$/;
+export const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
+
+export function normalizeFilePrefix(prefix: string): string {
+  if (prefix.endsWith("/")) {
+    return prefix + "*";
+  }
+  return prefix;
+}

package/src/commands/cloud.ts

@@ -24,6 +24,8 @@ import {
   readJournal,
   getJournalPath,
   type ConflictStrategy,
+  type EntityContext,
+  type SyncProgressEvent,
 } from "@indigoai-us/hq-cloud";
 
 import {
@@ -59,35 +61,119 @@ export function registerCloudCommands(program: Command): void {
       "--on-conflict <strategy>",
       "Conflict strategy: overwrite | keep | abort (omit for interactive)",
     )
+    .option(
+      "--creds-from-stdin",
+      "Read a pre-vended EntityContext as JSON from stdin instead of vending " +
+        "via the cached Cognito session. Use when the caller (e.g. AppBar HQ " +
+        "Sync) has its own STS pipeline (`/sts/vend-child` with task scope) " +
+        "and just needs share()'s upload mechanics. The caller is responsible " +
+        "for vending credentials with enough TTL for the run.",
+    )
+    .option(
+      "--json",
+      "Emit each share()-level event as a JSON Lines record on stderr (one " +
+        "JSON object per line) instead of human-readable console output. A " +
+        "synthetic `{type:\"complete\",...}` line is appended at the end with " +
+        "the final ShareResult. Subprocess callers parse these to render their " +
+        "own UI (e.g. AppBar Tauri events).",
+    )
     .action(
       async (
         paths: string[],
         options: CommonSyncOptions & {
           message?: string;
           onConflict?: ConflictStrategy;
+          credsFromStdin?: boolean;
+          json?: boolean;
         },
       ) => {
+        const jsonMode = options.json === true;
+        // Suppress the human banner/result output in JSON mode — the parent
+        // process renders its own UI from the stderr ndjson stream.
+        const log = (msg: string): void => {
+          if (!jsonMode) console.log(msg);
+        };
+        const emitJson = (event: Record<string, unknown>): void => {
+          process.stderr.write(JSON.stringify(event) + "\n");
+        };
+
         try {
           const targetPaths =
             paths && paths.length > 0 ? paths : [process.cwd()];
 
-          console.log(chalk.bold("\nHQ Sync — Push"));
-          console.log(`  HQ root:  ${options.hqRoot}`);
-          console.log(`  Company:  ${options.company ?? "(from .hq/config.json)"}`);
-          console.log(`  Paths:    ${targetPaths.join(", ")}\n`);
+          log(chalk.bold("\nHQ Sync — Push"));
+          log(`  HQ root:  ${options.hqRoot}`);
+          log(
+            `  Company:  ${options.company ?? "(from .hq/config.json or stdin)"}`,
+          );
+          log(`  Paths:    ${targetPaths.join(", ")}\n`);
+
+          // Resolve credentials. Two paths:
+          //   1. --creds-from-stdin: parse JSON EntityContext from stdin (the
+          //      AppBar shell-out contract — vend-child upstream, pipe in here).
+          //   2. default: vend via cached Cognito session (the human CLI path).
+          let entityContext: EntityContext | undefined;
+          let vaultConfig: ReturnType<typeof buildVaultConfig> | undefined;
+
+          if (options.credsFromStdin) {
+            if (process.stdin.isTTY) {
+              throw new Error(
+                "--creds-from-stdin requires JSON on stdin, but stdin is a " +
+                  "TTY. Pipe the EntityContext JSON via subprocess stdin " +
+                  "(e.g. `echo '{...}' | hq sync push --creds-from-stdin ...`).",
+              );
+            }
+            const raw = await readAllStdin();
+            try {
+              entityContext = JSON.parse(raw) as EntityContext;
+            } catch (e) {
+              throw new Error(
+                `--creds-from-stdin: failed to parse stdin as JSON: ${
+                  e instanceof Error ? e.message : String(e)
+                }`,
+              );
+            }
+          } else {
+            const accessToken = await ensureCognitoToken();
+            vaultConfig = buildVaultConfig(accessToken);
+          }
+
+          // In JSON mode, forward every share() event verbatim to stderr as
+          // ndjson. In human mode, share()'s defaultConsoleLogger handles the
+          // rendering (no onEvent → falls through to stdout/stderr printing).
+          const onEvent = jsonMode
+            ? (event: SyncProgressEvent): void =>
+                emitJson(event as unknown as Record<string, unknown>)
+            : undefined;
 
-          const accessToken = await ensureCognitoToken();
           const result = await share({
             paths: targetPaths,
             company: options.company,
             message: options.message,
             onConflict: options.onConflict,
-            vaultConfig: buildVaultConfig(accessToken),
+            vaultConfig,
+            entityContext,
             hqRoot: options.hqRoot,
+            onEvent,
           });
 
+          if (jsonMode) {
+            // Synthetic terminal event so subprocess consumers can read final
+            // counts without summing per-file events. Distinguished from
+            // SyncProgressEvent by `type:"complete"` (not in the share()
+            // event schema — added at the CLI seam).
+            emitJson({
+              type: "complete",
+              filesUploaded: result.filesUploaded,
+              bytesUploaded: result.bytesUploaded,
+              filesSkipped: result.filesSkipped,
+              conflictPaths: result.conflictPaths,
+              aborted: result.aborted,
+            });
+          }
+
           if (result.aborted) {
-            console.log(
+            log(
               chalk.yellow(
                 `\n⚠ Push aborted (${result.filesUploaded} uploaded, ${result.filesSkipped} skipped)`,
               ),
@@ -95,16 +181,21 @@ export function registerCloudCommands(program: Command): void {
             process.exit(1);
           }
 
-          console.log(
+          log(
             chalk.green(
               `\n✓ Pushed ${result.filesUploaded} file(s) (${formatBytes(result.bytesUploaded)}, ${result.filesSkipped} skipped)`,
             ),
           );
         } catch (err) {
-          console.error(
-            chalk.red("\n✗ Push failed:"),
-            err instanceof Error ? err.message : String(err),
-          );
+          const message = err instanceof Error ? err.message : String(err);
+          if (jsonMode) {
+            // In JSON mode, the parent process is parsing stderr for ndjson —
+            // human-formatted error lines would corrupt the stream. Emit a
+            // structured `fatal` event instead and let the parent surface it.
+            emitJson({ type: "fatal", message });
+          } else {
+            console.error(chalk.red("\n✗ Push failed:"), message);
+          }
           process.exit(1);
         }
       },
@@ -236,3 +327,19 @@ function formatBytes(bytes: number): string {
   const value = bytes / Math.pow(1024, exponent);
   return `${value.toFixed(value >= 100 || exponent === 0 ? 0 : 1)} ${units[exponent]}`;
 }
+
+/**
+ * Read all of stdin as a UTF-8 string. Used by `--creds-from-stdin` to
+ * receive a JSON-serialized EntityContext from the parent process (e.g.
+ * AppBar HQ Sync). Returns the empty string when stdin closes immediately.
+ *
+ * Caller is expected to detect TTY first — this function will block forever
+ * waiting for stdin to close if invoked interactively.
+ */
+async function readAllStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}

package/src/commands/files.ts

@@ -0,0 +1,227 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch, getCompanyUid } from "./secrets.js";
+import { GROUP_ID_PATTERN, EMAIL_PATTERN, normalizeFilePrefix } from "./_patterns.js";
+
+export function registerFilesCommand(program: Command): void {
+  const files = program
+    .command("files")
+    .description("Manage file access controls in HQ vault")
+    .option("--company <slug>", "Company slug (resolves to companyUid)");
+
+  files
+    .command("share <prefix>")
+    .description("Share a file prefix with a person or group")
+    .requiredOption("--with <principal>", "Email address or group id to share with")
+    .requiredOption("--permission <level>", "Permission level: read | write")
+    .action(async (prefix: string, opts: { with: string; permission: string }) => {
+      try {
+        const canonicalPrefix = normalizeFilePrefix(prefix);
+
+        if (!["read", "write"].includes(opts.permission)) {
+          console.error(chalk.red(`Invalid permission '${opts.permission}': must be one of read, write`));
+          process.exit(1);
+        }
+
+        const principal = opts.with;
+        const isEmail = EMAIL_PATTERN.test(principal);
+        const isGroup = GROUP_ID_PATTERN.test(principal);
+        if (!isEmail && !isGroup) {
+          console.error(chalk.red(`Invalid principal '${principal}': must be an email address or a group id matching grp_<alphanumeric>`));
+          process.exit(1);
+        }
+        const granteeType = isEmail ? "email" : "group";
+        const granteeId = isEmail ? principal.trim().toLowerCase() : principal;
+
+        const token = await ensureCognitoToken();
+        const companySlug = files.opts().company as string | undefined;
+        const companyUid = await getCompanyUid(token, companySlug);
+
+        const res = await vaultApiFetch({
+          token,
+          path: `/files/${encodeURIComponent(companyUid)}/acl/grant`,
+          method: "POST",
+          body: { prefix: canonicalPrefix, granteeType, granteeId, permission: opts.permission },
+        });
+
+        if (!res.ok) {
+          const body = await res.json().catch(() => ({})) as Record<string, string>;
+          if (res.status === 401) {
+            console.error(chalk.red("Not authenticated — please run `hq login`"));
+          } else if (res.status === 403) {
+            console.error(chalk.red("Not authorized to share this file prefix"));
+          } else if (res.status === 404) {
+            console.error(chalk.red("ACL record not found — the prefix may not have an ACL yet"));
+          } else if (res.status === 409) {
+            console.error(chalk.red("Concurrent modification — please retry"));
+          } else if (res.status >= 500) {
+            console.error(chalk.red(`Server error: ${body.error ?? res.statusText}`));
+          } else {
+            console.error(chalk.red(body.message ?? body.error ?? "Invalid request"));
+          }
+          process.exit(1);
+        }
+
+        const data = await res.json() as { acl?: { prefix?: string } };
+        const printedPrefix = data.acl?.prefix ?? canonicalPrefix;
+        console.log(chalk.green(`Granted ${opts.permission} on ${printedPrefix} to ${granteeId}`));
+      } catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
+  files
+    .command("unshare <prefix>")
+    .description("Remove a file access grant")
+    .requiredOption("--with <principal>", "Email address or group id to remove")
+    .action(async (prefix: string, opts: { with: string }) => {
+      try {
+        const canonicalPrefix = normalizeFilePrefix(prefix);
+
+        const principal = opts.with;
+        const isEmail = EMAIL_PATTERN.test(principal);
+        const isGroup = GROUP_ID_PATTERN.test(principal);
+        if (!isEmail && !isGroup) {
+          console.error(chalk.red(`Invalid principal '${principal}': must be an email address or a group id matching grp_<alphanumeric>`));
+          process.exit(1);
+        }
+        const granteeType = isEmail ? "email" : "group";
+        const granteeId = isEmail ? principal.trim().toLowerCase() : principal;
+
+        const token = await ensureCognitoToken();
+        const companySlug = files.opts().company as string | undefined;
+        const companyUid = await getCompanyUid(token, companySlug);
+
+        const res = await vaultApiFetch({
+          token,
+          path: `/files/${encodeURIComponent(companyUid)}/acl/revoke`,
+          method: "POST",
+          body: { prefix: canonicalPrefix, granteeType, granteeId },
+        });
+
+        if (!res.ok) {
+          const body = await res.json().catch(() => ({})) as Record<string, string>;
+          if (res.status === 401) {
+            console.error(chalk.red("Not authenticated — please run `hq login`"));
+          } else if (res.status === 403) {
+            console.error(chalk.red("Not authorized to modify this file prefix's ACL"));
+          } else if (res.status === 404) {
+            console.log(chalk.green(`Grant already absent for '${canonicalPrefix}' / ${granteeId}`));
+            return;
+          } else if (res.status >= 500) {
+            console.error(chalk.red(`Server error: ${body.error ?? res.statusText}`));
+          } else {
+            console.error(chalk.red(body.message ?? body.error ?? "Invalid request"));
+          }
+          process.exit(1);
+        }
+
+        console.log(chalk.green(`Removed grant for ${granteeId} on '${canonicalPrefix}'`));
+      } catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
+  files
+    .command("acl <prefix>")
+    .description("Show the ACL (access control list) for a file prefix")
+    .action(async (prefix: string) => {
+      try {
+        const canonicalPrefix = normalizeFilePrefix(prefix);
+
+        const token = await ensureCognitoToken();
+        const companySlug = files.opts().company as string | undefined;
+        const companyUid = await getCompanyUid(token, companySlug);
+
+        const res = await vaultApiFetch({
+          token,
+          path: `/files/${encodeURIComponent(companyUid)}/acl`,
+          query: { prefix: canonicalPrefix },
+        });
+
+        if (!res.ok) {
+          const body = await res.json().catch(() => ({})) as Record<string, string>;
+          if (res.status === 401) {
+            console.error(chalk.red("Not authenticated — please run `hq login`"));
+          } else if (res.status === 403) {
+            console.error(chalk.red("Not authorized to view this file prefix's ACL"));
+          } else if (res.status === 404) {
+            console.error(chalk.red(`No ACL record exists for '${canonicalPrefix}'`));
+          } else if (res.status >= 500) {
+            console.error(chalk.red(`Server error: ${body.error ?? res.statusText}`));
+          } else {
+            console.error(chalk.red(body.message ?? body.error ?? "Invalid request"));
+          }
+          process.exit(1);
+        }
+
+        const data = await res.json() as {
+          acl: {
+            itemType: string;
+            companyUid: string;
+            prefix: string;
+            creatorUid: string;
+            open?: boolean;
+            entries: Array<{
+              granteeType: string;
+              granteeId: string;
+              permission: string;
+              grantedBy: string;
+              grantedAt: string;
+            }>;
+            effectivePermission?: string | null;
+            createdAt: string;
+            updatedAt: string;
+          };
+        };
+
+        const acl = data.acl;
+        const aclStatus = acl.open ? "open" : "restricted";
+
+        console.log(chalk.green(`ACL for ${acl.prefix} (${aclStatus})`));
+        console.log(`Creator: ${acl.creatorUid}`);
+        if (acl.effectivePermission) {
+          console.log(`Your effective permission: ${acl.effectivePermission}`);
+        }
+
+        if (acl.entries.length === 0) {
+          if (acl.open) {
+            console.log(chalk.gray("Open ACL — all active members have read access."));
+          } else {
+            console.log(chalk.gray("No explicit grants — only creator has access."));
+          }
+          return;
+        }
+
+        console.log("Entries:");
+        const TYPE_W = Math.max(4, ...acl.entries.map((e) => e.granteeType.length));
+        const GRANTEE_W = Math.max(7, ...acl.entries.map((e) => e.granteeId.length));
+        const PERM_W = Math.max(10, ...acl.entries.map((e) => e.permission.length));
+        const BY_W = Math.max(10, ...acl.entries.map((e) => e.grantedBy.length));
+        const tableHeader = [
+          "TYPE".padEnd(TYPE_W),
+          "GRANTEE".padEnd(GRANTEE_W),
+          "PERMISSION".padEnd(PERM_W),
+          "GRANTED_BY".padEnd(BY_W),
+          "GRANTED_AT",
+        ].join("  ");
+        console.log(chalk.bold(tableHeader));
+        for (const e of acl.entries) {
+          const grantedAt = e.grantedAt.slice(0, 10);
+          console.log([
+            e.granteeType.padEnd(TYPE_W),
+            e.granteeId.padEnd(GRANTEE_W),
+            e.permission.padEnd(PERM_W),
+            e.grantedBy.padEnd(BY_W),
+            grantedAt,
+          ].join("  "));
+        }
+      } catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+}

package/src/index.ts

@@ -24,6 +24,7 @@ import { registerTeamSyncCommand } from "./commands/team-sync.js";
 import { registerAuthCommands } from "./commands/auth.js";
 import { registerSecretsCommand } from "./commands/secrets.js";
 import { registerGroupsCommand } from "./commands/groups.js";
+import { registerFilesCommand } from "./commands/files.js";
 
 initSentry();
 
@@ -32,7 +33,7 @@ const program = new Command();
 program
   .name("hq")
   .description("HQ management CLI — modules, packages, and cloud sync")
-  .version("5.5.0");
+  .version("5.8.3");
 
 // Module management subcommand group
 const modulesCmd = program
@@ -92,6 +93,9 @@ registerSecretsCommand(program);
 // Groups management (subcommand group — hq groups create|delete|add|remove|list|members)
 registerGroupsCommand(program);
 
+// Files ACL management (subcommand group — hq files share|unshare|acl)
+registerFilesCommand(program);
+
 // Onboarding (top-level — Cognito + vault-service provisioning)
 registerOnboardCommand(program);
 

package/src/utils/cognito-session.ts

@@ -50,8 +50,7 @@ export const DEFAULT_COGNITO: CognitoAuthConfig = {
 };
 
 export const DEFAULT_VAULT_API_URL =
-  process.env.HQ_VAULT_API_URL ??
-  "https://4nfy67z28h.execute-api.us-east-1.amazonaws.com";
+  process.env.HQ_VAULT_API_URL ?? "https://hqapi.getindigo.ai";
 
 export const DEFAULT_HQ_ROOT = path.join(os.homedir(), "hq");