@indigoai-us/hq-cli 5.77.10 → 5.77.12

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## [Unreleased]
 
+## [5.77.12]
+
+### Added
+
+- `HQ_API_KEY` fail-closed consume path: `hqk_…` keys route `hq secrets get`
+  / `exec` / `env` through vault key fetch; Cognito-only commands hard-error.
+- `hq api-keys create --deploy-app` (repeatable) and deploy-app column in list
+  output for identity-bound deploy keys. (#270)
+
+## [5.77.11]
+
+### Fixed
+
+- `hq members promote <email>` now looks up the active member roster by
+  `personEmail` (and maps fleet-agent machine emails like revoke) instead of
+  synthesizing a pending-only `email:…#cmp` membership key that the role API
+  cannot find. (#269)
+- Re-inviting an email that already has a pending invite no longer claims the
+  person is already a member; the CLI distinguishes pending vs active and
+  suggests `hq members invite <email> --company <slug> --resend` when
+  appropriate. (#269)
+
+## [5.77.10]
+
+### Fixed
+
+- Updated `@indigoai-us/hq-cloud` to 6.14.27 so the sync watcher no longer
+  descends into directory-only ignores such as nested `node_modules/`, which
+  could exhaust host inotify watches. (#268)
+
 ## [5.77.9]
 
 ### Added

package/dist/commands/api-keys.js

@@ -1,6 +1,11 @@
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { assertCognitoOnlyCommand } from "../utils/resolve-vault-credential.js";
 import { getCompanyUid, vaultApiFetch } from "./secrets.js";
+async function requireCognitoForApiKeys(label) {
+    assertCognitoOnlyCommand(label);
+    return ensureCognitoToken();
+}
 function collectRepeatedOption(value, previous) {
     return [...previous, value];
 }
@@ -10,6 +15,11 @@ function formatMaybe(value) {
 function formatPrefixes(prefixes) {
     return prefixes.length > 0 ? prefixes.join(", ") : "-";
 }
+function formatDeployApps(deploy) {
+    if (!deploy?.apps?.length)
+        return "-";
+    return deploy.apps.join(", ");
+}
 function parsePermission(value) {
     if (value === "read" || value === "write" || value === "admin") {
         return value;
@@ -51,6 +61,7 @@ function renderApiKeysTable(apiKeys) {
         name: apiKey.name,
         permission: apiKey.scope.permission,
         prefixes: formatPrefixes(apiKey.scope.allowedPrefixes),
+        deployApps: formatDeployApps(apiKey.scope.deploy),
         status: apiKey.status,
         lastUsedAt: formatMaybe(apiKey.lastUsedAt),
         expiresAt: formatMaybe(apiKey.expiresAt),
@@ -59,6 +70,7 @@ function renderApiKeysTable(apiKeys) {
     const nameWidth = Math.max(4, ...rows.map((row) => row.name.length));
     const permissionWidth = Math.max(10, ...rows.map((row) => row.permission.length));
     const prefixesWidth = Math.max(8, ...rows.map((row) => row.prefixes.length));
+    const deployWidth = Math.max(6, ...rows.map((row) => row.deployApps.length));
     const statusWidth = Math.max(6, ...rows.map((row) => row.status.length));
     const lastUsedWidth = Math.max(11, ...rows.map((row) => row.lastUsedAt.length));
     const expiresWidth = Math.max(10, ...rows.map((row) => row.expiresAt.length));
@@ -67,6 +79,7 @@ function renderApiKeysTable(apiKeys) {
         "NAME".padEnd(nameWidth),
         "PERMISSION".padEnd(permissionWidth),
         "PREFIXES".padEnd(prefixesWidth),
+        "DEPLOY".padEnd(deployWidth),
         "STATUS".padEnd(statusWidth),
         "LAST USED".padEnd(lastUsedWidth),
         "EXPIRES".padEnd(expiresWidth),
@@ -78,6 +91,7 @@ function renderApiKeysTable(apiKeys) {
             row.name.padEnd(nameWidth),
             row.permission.padEnd(permissionWidth),
             row.prefixes.padEnd(prefixesWidth),
+            row.deployApps.padEnd(deployWidth),
             row.status.padEnd(statusWidth),
             row.lastUsedAt.padEnd(lastUsedWidth),
             row.expiresAt.padEnd(expiresWidth),
@@ -91,20 +105,21 @@ export function registerApiKeysCommand(program) {
         .option("--company <slug>", "Company slug (resolves to companyUid)");
     apiKeys
         .command("create")
-        .description("Create a new API key")
+        .description("Create a new API key (vault secrets and/or scoped deploy via --deploy-app)")
         .requiredOption("--name <label>", "Human-readable label for the API key")
-        .option("--scope <prefix>", "Allowed prefix (repeatable)", collectRepeatedOption, [])
-        .option("--permission <level>", "Permission level: read | write | admin", "read")
+        .option("--scope <prefix>", "Allowed secret prefix (repeatable)", collectRepeatedOption, [])
+        .option("--deploy-app <id>", "Deploy app id/slug allowed for publish (repeatable)", collectRepeatedOption, [])
+        .option("--permission <level>", "Secret permission level: read | write | admin (required when --scope is set)", "read")
         .option("--expires <ISO8601>", "Optional ISO-8601 expiry timestamp")
         .action(async (opts) => {
         try {
-            if (opts.scope.length === 0) {
-                console.error(chalk.red("Error: at least one --scope <prefix> is required."));
+            if (opts.scope.length === 0 && opts.deployApp.length === 0) {
+                console.error(chalk.red("Error: provide at least one --scope <prefix> and/or --deploy-app <id>."));
                 process.exit(1);
             }
             const permission = parsePermission(opts.permission);
             const expiresAt = parseExpires(opts.expires);
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoForApiKeys("api-keys create");
             const companyUid = await getCompanyUid(token, apiKeys.opts().company);
             const res = await vaultApiFetch({
                 token,
@@ -113,8 +128,20 @@ export function registerApiKeysCommand(program) {
                 body: {
                     companyUid,
                     name: opts.name,
-                    allowedPrefixes: opts.scope,
-                    permission,
+                    ...(opts.scope.length > 0
+                        ? { allowedPrefixes: opts.scope, permission }
+                        : {}),
+                    ...(opts.deployApp.length > 0
+                        ? {
+                            deploy: {
+                                apps: opts.deployApp,
+                                capabilities: ["deploy:write"],
+                            },
+                        }
+                        : {}),
+                    ...(opts.scope.length === 0 && opts.deployApp.length > 0
+                        ? { permission }
+                        : {}),
                     ...(expiresAt ? { expiresAt } : {}),
                 },
             });
@@ -131,10 +158,26 @@ export function registerApiKeysCommand(program) {
             console.log(`  Company: ${data.apiKey.companyUid}`);
             console.log(`  Permission: ${data.apiKey.scope.permission}`);
             console.log(`  Prefixes: ${formatPrefixes(data.apiKey.scope.allowedPrefixes)}`);
+            console.log(`  Deploy apps: ${formatDeployApps(data.apiKey.scope.deploy)}`);
             console.log(`  Status: ${data.apiKey.status}`);
             console.log(`  Created: ${data.apiKey.createdAt}`);
             console.log(`  Last used: ${formatMaybe(data.apiKey.lastUsedAt)}`);
             console.log(`  Expires: ${formatMaybe(data.apiKey.expiresAt)}`);
+            console.log("");
+            console.log(chalk.bold("Usage"));
+            console.log("  This key acts as you (Cognito identity), limited to the scopes above.");
+            console.log("  Export it for automation (never falls back to a session):");
+            console.log(`\n  export HQ_API_KEY='${data.key.value}'\n`);
+            console.log("  Vault secrets:");
+            console.log("    hq secrets get <NAME> --reveal");
+            console.log("    hq secrets exec --only <NAME> -- <command>");
+            console.log("    Or HTTP: POST /v1/keys/secrets/fetch with Authorization: Bearer <key>");
+            if (data.apiKey.scope.deploy?.apps?.length) {
+                console.log("  Deploy (scoped apps only):");
+                console.log("    Authorization: Bearer <key> against the hq-deploy API");
+                console.log(chalk.dim("    Cannot change access-mode, password, or mint hqd_ keys."));
+            }
+            console.log(chalk.dim("  Unsupported under HQ_API_KEY: secrets list/set/share/acl (use a Cognito session)."));
         }
         catch (err) {
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
@@ -146,7 +189,7 @@ export function registerApiKeysCommand(program) {
         .description("List API keys for a company")
         .action(async () => {
         try {
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoForApiKeys("api-keys list");
             const companyUid = await getCompanyUid(token, apiKeys.opts().company);
             const res = await vaultApiFetch({
                 token,
@@ -173,7 +216,7 @@ export function registerApiKeysCommand(program) {
         .description("Revoke an API key")
         .action(async (keyId) => {
         try {
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoForApiKeys("api-keys revoke");
             const res = await vaultApiFetch({
                 token,
                 path: `/v1/api-keys/${encodeURIComponent(keyId)}/revoke`,

package/dist/commands/members.d.ts

@@ -142,6 +142,14 @@ export declare class InviteHttpError extends Error {
 export declare function formatInviteHttpError(status: number, fallback: string, code?: string): string;
 export declare function listPendingInvites(token: string, companyUid: string): Promise<PendingInvite[]>;
 export declare function listActiveMembers(token: string, companyUid: string): Promise<ActiveMember[]>;
+/**
+ * Resolve a role-change target to an active membership key.
+ *
+ * Pending invites are email-keyed, but claimed active memberships are keyed by
+ * personUid. Consequently, role changes must look up email targets in the
+ * active member list instead of synthesizing an `email:...#company` key.
+ */
+export declare function resolveRoleChangeTarget(token: string, companyUid: string, target: string): Promise<string>;
 /**
  * Resolve a `revoke` CLI argument into the canonical `membershipKey` shape
  * the server requires. Accepts three input forms:

package/dist/commands/members.js

@@ -244,6 +244,39 @@ export async function listActiveMembers(token, companyUid) {
     const data = (await res.json());
     return data?.members ?? [];
 }
+/**
+ * Resolve a role-change target to an active membership key.
+ *
+ * Pending invites are email-keyed, but claimed active memberships are keyed by
+ * personUid. Consequently, role changes must look up email targets in the
+ * active member list instead of synthesizing an `email:...#company` key.
+ */
+export async function resolveRoleChangeTarget(token, companyUid, target) {
+    if (target.includes("#"))
+        return target;
+    const detected = detectTarget(target);
+    if (detected?.type === "person" || detected?.type === "agent") {
+        return `${detected.value}#${companyUid}`;
+    }
+    if (detected?.type === "email") {
+        // Active fleet-agent guest memberships are keyed agt_…#cmp_…, not by
+        // personEmail enrichment. Map machine emails the same way revoke does
+        // before falling through to the human roster lookup.
+        if (detected.isAgent) {
+            const local = detected.value.split("@")[0] ?? "";
+            const m = local.match(/^agt-(.+)$/i);
+            if (m)
+                return `agt_${m[1].toUpperCase()}#${companyUid}`;
+        }
+        const members = await listActiveMembers(token, companyUid);
+        const member = members.find((candidate) => candidate.personEmail?.trim().toLowerCase() === detected.value);
+        if (member)
+            return member.membershipKey;
+        throw new Error(`No active member has email '${detected.value}' in this company. ` +
+            "Run `hq members list` to find the member, or use their prs_ personUid.");
+    }
+    throw new Error(`Invalid target '${target}': use an email, prs_ personUid, agt_ agentUid, or full membership key`);
+}
 /**
  * Resolve a `revoke` CLI argument into the canonical `membershipKey` shape
  * the server requires. Accepts three input forms:
@@ -356,7 +389,7 @@ export function registerMembersCommand(program) {
             const token = await ensureCognitoToken();
             const companySlug = members.opts().company;
             const companyUid = await getCompanyUid(token, companySlug);
-            const membershipKey = resolveRevokeTargetToMembershipKey(target, companyUid);
+            const membershipKey = await resolveRoleChangeTarget(token, companyUid, target);
             await changeMemberRole(token, companyUid, membershipKey, role);
             console.log(chalk.green(`Updated role for '${target}' to ${role}`));
             if (role === "owner" || role === "admin") {
@@ -388,10 +421,13 @@ export function registerMembersCommand(program) {
         .option("--no-send-email", "Skip the server-side Resend send — only create the pending DDB row. Useful when you're scripting bulk invites and will send the announcement out-of-band.")
         .option("--resend", "Re-fire the invitation email against an existing pending row without creating a new row. Maps to hq-pro `resend: true` short-circuit. Email-keyed invites only.")
         .action(async (target, opts) => {
+        let token;
+        let companyUid;
+        let companySlug;
         try {
-            const token = await ensureCognitoToken();
-            const companySlug = members.opts().company;
-            const companyUid = await getCompanyUid(token, companySlug);
+            token = await ensureCognitoToken();
+            companySlug = members.opts().company;
+            companyUid = await getCompanyUid(token, companySlug);
             const callerUid = await getCallerPersonUid(token);
             // --resend short-circuits to the server's re-fire path. No new row.
             if (opts.resend === true) {
@@ -511,13 +547,50 @@ export function registerMembersCommand(program) {
             }
         }
         catch (err) {
-            // The target is ALREADY an active member (409 MEMBERSHIP_ALREADY_EXISTS).
-            // Terminal, not a failure: the person is already in the company, so
-            // there's nothing to invite or retry. Print a plain note and exit 0 —
-            // re-attempting just re-fires the server's (correctly captured) 409,
-            // and a bulk-invite script shouldn't abort on an already-member. HQ-11.
+            // A 409 may refer to either an active membership or an existing
+            // pending invite. Probe both views so email targets get actionable
+            // guidance while preserving the terminal exit-0 behavior for bulk
+            // invite scripts.
             if (err instanceof InviteHttpError &&
                 err.code === "MEMBERSHIP_ALREADY_EXISTS") {
+                const detected = detectTarget(target);
+                const normalizedEmail = detected?.type === "email" ? detected.value : undefined;
+                if (normalizedEmail && token && companyUid) {
+                    // Preserve --company in copy-paste hints so multi-company
+                    // callers don't hit "Multiple active companies" on --resend.
+                    const companyFlag = companySlug
+                        ? ` --company ${companySlug}`
+                        : "";
+                    const resendHint = `hq members invite ${normalizedEmail}${companyFlag} --resend`;
+                    try {
+                        const pending = await listPendingInvites(token, companyUid);
+                        if (pending.some((invite) => invite.inviteeEmail?.trim().toLowerCase() ===
+                            normalizedEmail)) {
+                            console.log(chalk.yellow(`${normalizedEmail} already has a pending invite. ` +
+                                `Use \`${resendHint}\` to re-send it.`));
+                            return;
+                        }
+                    }
+                    catch {
+                        // Pending-list visibility can vary by server version or role.
+                        // Fall through to the active-member probe and generic copy.
+                    }
+                    try {
+                        const activeMembers = await listActiveMembers(token, companyUid);
+                        if (activeMembers.some((member) => member.personEmail?.trim().toLowerCase() ===
+                            normalizedEmail)) {
+                            console.log(chalk.yellow(`${normalizedEmail} is already a member of this company — nothing to do.`));
+                            return;
+                        }
+                    }
+                    catch {
+                        // Preserve the original conflict as the source of truth and
+                        // use copy that remains accurate when the probes are hidden.
+                    }
+                    console.log(chalk.yellow(`${normalizedEmail} already has a membership or pending invite for this company. ` +
+                        `If the invite is pending, use \`${resendHint}\`.`));
+                    return;
+                }
                 console.log(chalk.yellow(`${target.toLowerCase()} is already a member of this company — nothing to do.`));
                 return;
             }

package/dist/commands/secrets.js

@@ -8,8 +8,14 @@ import { computeSha256 } from "../utils/integrity.js";
 import { SECRET_NAME_PATTERN, GROUP_ID_PATTERN, EMAIL_PATTERN } from "./_patterns.js";
 import { describeSecretsScope, formatSecretSaved, formatSecretsListEmpty, formatSecretsListHeader, } from "./secrets-scope.js";
 import { vaultApiFetch, getCompanyUid, getEntityUid, } from "../utils/vault-api.js";
+import { HQ_API_KEY_PREFIX, assertCognitoOnlyCommand, resolveVaultCredential, } from "../utils/resolve-vault-credential.js";
 import { SandboxRunnerClient, } from "../utils/sandbox-runner-client.js";
 export { vaultApiFetch, getCompanyUid, getEntityUid };
+/** Cognito session for secrets commands that do not support HQ_API_KEY. */
+async function requireCognitoTokenForSecrets(commandLabel) {
+    assertCognitoOnlyCommand(commandLabel);
+    return ensureCognitoToken();
+}
 function scopeOpts(opts) {
     if (opts.personal && opts.company) {
         console.error(chalk.red("Error: --personal cannot be combined with --company."));
@@ -424,7 +430,54 @@ function renderPolicyScripts(scripts) {
 // Requests are chunked at MAX_BATCH_NAMES and throw on the FIRST unresolved key
 // with the same `Failed to fetch secret '<k>': <reason>` shape the per-key GET
 // path used — never swallows a failure.
+async function loadRevealedSecretsViaApiKey(token, keys) {
+    const resolved = new Map();
+    const requested = [...new Set(keys)];
+    const cacheScope = "__api_key__";
+    for (const name of requested) {
+        const res = await vaultApiFetch({
+            token,
+            path: "/v1/keys/secrets/fetch",
+            method: "POST",
+            body: { name },
+            signal: AbortSignal.timeout(SECRET_LOAD_TIMEOUT_MS),
+        });
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            if (res.status === 404) {
+                throw new Error(`Failed to fetch secret '${name}': Secret not found`);
+            }
+            if (res.status === 403) {
+                const message = typeof body.error === "string"
+                    ? body.error
+                    : typeof body.message === "string"
+                        ? body.message
+                        : "No read permission";
+                if (body.highSecurity === true) {
+                    throw new Error(highSecuritySandboxOnlyMessage(name));
+                }
+                throw new Error(`Failed to fetch secret '${name}': ${message}`);
+            }
+            if (res.status === 401) {
+                throw new Error(`Failed to fetch secret '${name}': Invalid or missing API key`);
+            }
+            throw new Error(`Failed to fetch secret '${name}': ${extractApiMessage(body, res.statusText)}`);
+        }
+        const secret = typeof body.secret === "object" && body.secret !== null
+            ? body.secret
+            : null;
+        if (typeof secret?.value !== "string") {
+            throw new Error(`Failed to fetch secret '${name}': malformed fetch response`);
+        }
+        removeCacheEntry(cacheScope, name);
+        resolved.set(name, secret.value);
+    }
+    return resolved;
+}
 export async function loadRevealedSecrets(token, companyUid, keys, usage) {
+    if (token.startsWith(HQ_API_KEY_PREFIX)) {
+        return loadRevealedSecretsViaApiKey(token, keys);
+    }
     const resolved = new Map();
     const requested = [...new Set(keys)];
     try {
@@ -632,7 +685,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red(`Secret value exceeds 4096-byte SSM limit (got ${Buffer.byteLength(value, "utf8")} bytes).`));
                 process.exit(1);
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets set");
             const scope = scopeOpts(secrets.opts());
             const companyUid = await getEntityUid(token, scope);
             const scopeLabel = describeSecretsScope({
@@ -677,7 +730,52 @@ export function registerSecretsCommand(program) {
         .option("--reveal", "Include the decrypted secret value")
         .action(async (name, opts) => {
         try {
-            const token = await ensureCognitoToken();
+            const cred = await resolveVaultCredential();
+            if (cred.kind === "api-key") {
+                const res = await vaultApiFetch({
+                    token: cred.token,
+                    path: "/v1/keys/secrets/fetch",
+                    method: "POST",
+                    body: { name },
+                });
+                const body = (await res.json().catch(() => ({})));
+                if (!res.ok) {
+                    if (res.status === 403 && body.highSecurity === true) {
+                        console.error(chalk.red(highSecuritySandboxOnlyMessage(name)));
+                        process.exit(1);
+                    }
+                    console.error(chalk.red(`Failed to get secret: ${extractApiMessage(body, res.statusText)}`));
+                    process.exit(1);
+                }
+                const secret = typeof body.secret === "object" && body.secret !== null
+                    ? body.secret
+                    : null;
+                if (!secret || typeof secret.name !== "string") {
+                    console.error(chalk.red("Failed to get secret: malformed response"));
+                    process.exit(1);
+                }
+                console.log(chalk.bold(`Secret: ${secret.name}`));
+                if (secret.lastModifiedDate) {
+                    console.log(`  Last Modified: ${secret.lastModifiedDate}`);
+                }
+                if (secret.version != null) {
+                    console.log(`  Version:       ${secret.version}`);
+                }
+                console.log(`  Tier:          ${normalizeSecretTier(secret.tier)}`);
+                console.log(`  Script Lock:   ${normalizeScriptLockMode(secret.scriptLock?.mode)}`);
+                if (opts.reveal) {
+                    if (typeof secret.value !== "string") {
+                        console.error(chalk.red("Failed to get secret: reveal requested but response omitted secret.value"));
+                        process.exit(1);
+                    }
+                    console.log(`  Value:         ${secret.value}`);
+                }
+                else {
+                    console.log(`  Value:         ${chalk.dim("[REDACTED]")}`);
+                }
+                return;
+            }
+            const token = cred.token;
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -748,7 +846,7 @@ export function registerSecretsCommand(program) {
         .option("--quiet", "Suppress the present/absent line (use the exit code only)")
         .action(async (name, opts) => {
         try {
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets exists");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -791,7 +889,7 @@ export function registerSecretsCommand(program) {
                 }
                 normalizedPrefix = normalized;
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets list");
             const scope = scopeOpts(secrets.opts());
             const companyUid = await getEntityUid(token, scope);
             const scopeLabel = describeSecretsScope({
@@ -865,7 +963,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red(`Invalid secret path '${secretPath}': must match ^[A-Z][A-Z0-9_]*(/[A-Z][A-Z0-9_]+)*$ (e.g. MY_KEY or PROD/DB_PASSWORD)`));
                 process.exit(1);
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -926,7 +1024,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red("Error: provide at least one of --tier or --lock-script."));
                 process.exit(1);
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -971,7 +1069,7 @@ export function registerSecretsCommand(program) {
                 process.exit(1);
             }
             const usage = await buildSecretUsage("exec", opts.script, opts.id, opts.attestation);
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -1009,7 +1107,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red(`Invalid secret path '${secretPath}': must match ^[A-Z][A-Z0-9_]*(/[A-Z][A-Z0-9_]+)*$ (e.g. MY_KEY or PROD/DB_PASSWORD)`));
                 process.exit(1);
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -1040,7 +1138,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red(`Invalid secret path '${secretPath}': must match ^[A-Z][A-Z0-9_]*(/[A-Z][A-Z0-9_]+)*$ (e.g. MY_KEY or PROD/DB_PASSWORD)`));
                 process.exit(1);
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -1087,7 +1185,7 @@ export function registerSecretsCommand(program) {
                     return;
                 }
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -1131,7 +1229,7 @@ export function registerSecretsCommand(program) {
                 process.exit(1);
             }
             const keys = parseSecretNameList(opts.only);
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const scope = scopeOpts(mergeScopeOpts(secrets.opts(), opts));
             const companyUid = await getEntityUid(token, scope);
             const client = new SandboxRunnerClient();
@@ -1184,9 +1282,13 @@ export function registerSecretsCommand(program) {
                 process.exit(1);
             }
             const keys = parseSecretNameList(_opts.only);
-            const token = await ensureCognitoToken();
-            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
-            const revealed = await loadRevealedSecrets(token, companyUid, keys, await buildSecretUsage("exec", _opts.script, _opts.scriptId));
+            const cred = await resolveVaultCredential();
+            const companyUid = cred.kind === "api-key"
+                ? "__api_key__"
+                : await getEntityUid(cred.token, scopeOpts(secrets.opts()));
+            const revealed = await loadRevealedSecrets(cred.token, companyUid, keys, cred.kind === "cognito"
+                ? await buildSecretUsage("exec", _opts.script, _opts.scriptId)
+                : undefined);
             const secretEnv = {};
             for (const key of keys) {
                 const value = revealed.get(key);
@@ -1231,9 +1333,13 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.yellow("stdout is a terminal — values redacted. Use: source <(hq secrets env --only KEY1,KEY2)"));
             }
             const keys = parseSecretNameList(opts.only);
-            const token = await ensureCognitoToken();
-            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
-            const revealed = await loadRevealedSecrets(token, companyUid, keys, await buildSecretUsage("env", opts.script, opts.scriptId));
+            const cred = await resolveVaultCredential();
+            const companyUid = cred.kind === "api-key"
+                ? "__api_key__"
+                : await getEntityUid(cred.token, scopeOpts(secrets.opts()));
+            const revealed = await loadRevealedSecrets(cred.token, companyUid, keys, cred.kind === "cognito"
+                ? await buildSecretUsage("env", opts.script, opts.scriptId)
+                : undefined);
             for (const key of keys) {
                 const value = revealed.get(key);
                 // loadRevealedSecrets throws on any unresolved key, so a miss here is
@@ -1270,7 +1376,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red("Maximum expiry is 7 days (7d)."));
                 process.exit(1);
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -1316,7 +1422,7 @@ export function registerSecretsCommand(program) {
             if (!principal) {
                 process.exit(1);
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -1373,7 +1479,7 @@ export function registerSecretsCommand(program) {
             if (!principal) {
                 process.exit(1);
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -1422,7 +1528,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red(`Invalid secret path '${path}': must match ^[A-Z][A-Z0-9_]*(/[A-Z][A-Z0-9_]+)*$ (e.g. MY_KEY or PROD/DB_PASSWORD)`));
                 process.exit(1);
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const secretPath = path;
             const res = await vaultApiFetch({

package/dist/utils/resolve-vault-credential.d.ts

@@ -0,0 +1,30 @@
+/** Vault API keys issued by `hq api-keys create` (hq-pro). */
+export declare const HQ_API_KEY_PREFIX = "hqk_";
+export type VaultCredential = {
+    kind: "api-key";
+    token: string;
+} | {
+    kind: "cognito";
+    token: string;
+};
+/**
+ * Raw HQ_API_KEY from the environment, trimmed. Undefined when unset/empty.
+ * Does not validate prefix — use {@link resolveVaultCredential} for that.
+ */
+export declare function peekHqApiKey(): string | undefined;
+/**
+ * Resolve vault auth for CLI commands.
+ *
+ * When `HQ_API_KEY` is set it is authoritative: must be a vault key (`hqk_…`)
+ * and Cognito is never used as a fallback (fail-closed). When unset, uses the
+ * cached Cognito session (interactive login if needed).
+ */
+export declare function resolveVaultCredential(options?: {
+    interactive?: boolean;
+}): Promise<VaultCredential>;
+/**
+ * Throw when HQ_API_KEY is set but the command only supports Cognito sessions
+ * (list, set, ACL, api-keys admin, etc.).
+ */
+export declare function assertCognitoOnlyCommand(commandLabel: string): void;
+//# sourceMappingURL=resolve-vault-credential.d.ts.map