hereya-cli 0.85.6 → 0.86.1

package/dist/commands/run/index.js

@@ -2,6 +2,8 @@ import { Args, Command, Flags } from '@oclif/core';
 import { getBackend } from '../../backend/index.js';
 import { getConfigManager } from '../../lib/config/index.js';
 import { getEnvManager } from '../../lib/env/index.js';
+import { withEphemeralToken } from '../../lib/ephemeral-token.js';
+import { getDefaultLogger } from '../../lib/log.js';
 import { getProfileFromWorkspace } from '../../lib/profile-utils.js';
 import { runShell } from '../../lib/shell.js';
 import { validateDevelopmentWorkspace } from '../../lib/workspace-validation.js';
@@ -19,6 +21,10 @@ export default class Run extends Command {
             description: 'directory to run command in',
             required: false,
         }),
+        token: Flags.string({
+            description: 'Ephemeral cloud access token used for this invocation only. Held in memory; never written to the keychain or `~/.hereya/secrets/`. Takes precedence over the HEREYA_TOKEN environment variable.',
+            required: false,
+        }),
         workspace: Flags.string({
             char: 'w',
             description: 'name of the workspace to run the command in',
@@ -27,6 +33,17 @@ export default class Run extends Command {
     };
     static strict = false;
     async run() {
+        const { flags } = await this.parse(Run);
+        // Precedence: --token flag > HEREYA_TOKEN env var > keychain.
+        if (flags.token) {
+            if (process.env.HEREYA_TOKEN) {
+                getDefaultLogger().debug('[run] --token flag overrides HEREYA_TOKEN environment variable.');
+            }
+            return withEphemeralToken(flags.token, () => this.runInner());
+        }
+        return this.runInner();
+    }
+    async runInner() {
         const { args, argv, flags } = await this.parse(Run);
         const projectRootDir = flags.chdir || process.env.HEREYA_PROJECT_ROOT_DIR;
         const configManager = getConfigManager();

package/dist/commands/search/index.d.ts

@@ -9,7 +9,9 @@ export default class Search extends Command {
         chdir: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
     private displayResults;
+    private runInner;
 }

package/dist/commands/search/index.js

@@ -1,6 +1,8 @@
 import { Args, Command, Flags } from '@oclif/core';
 import chalk from 'chalk';
 import { getBackend } from '../../backend/index.js';
+import { withEphemeralToken } from '../../lib/ephemeral-token.js';
+import { getDefaultLogger } from '../../lib/log.js';
 export default class Search extends Command {
     static args = {
         query: Args.string({
@@ -30,8 +32,44 @@ export default class Search extends Command {
             default: 20,
             description: 'Maximum number of results to return',
         }),
+        token: Flags.string({
+            description: 'Ephemeral cloud access token used for this invocation only. Held in memory; never written to the keychain or `~/.hereya/secrets/`. Takes precedence over the HEREYA_TOKEN environment variable.',
+            required: false,
+        }),
     };
     async run() {
+        const { flags } = await this.parse(Search);
+        // Precedence: --token flag > HEREYA_TOKEN env var > keychain.
+        if (flags.token) {
+            if (process.env.HEREYA_TOKEN) {
+                getDefaultLogger().debug('[search] --token flag overrides HEREYA_TOKEN environment variable.');
+            }
+            return withEphemeralToken(flags.token, () => this.runInner());
+        }
+        return this.runInner();
+    }
+    displayResults(packages, hasMore) {
+        if (packages.length === 0) {
+            this.log(chalk.yellow('No packages found matching your query.'));
+            return;
+        }
+        this.log(`Found ${chalk.bold(packages.length)} package(s):`);
+        this.log();
+        for (const pkg of packages) {
+            const visibilityBadge = pkg.visibility === 'PUBLIC'
+                ? chalk.green('PUBLIC')
+                : chalk.yellow('PRIVATE');
+            this.log(`  ${chalk.cyan.bold(`${pkg.name}@${pkg.version}`)} ${visibilityBadge}`);
+            if (pkg.description) {
+                this.log(`    ${chalk.gray(pkg.description)}`);
+            }
+            this.log();
+        }
+        if (hasMore) {
+            this.log(chalk.dim('More results available. Use --limit to see more.'));
+        }
+    }
+    async runInner() {
         const { args, flags } = await this.parse(Search);
         // Change to specified directory
         if (flags.chdir !== '.') {
@@ -66,25 +104,4 @@ export default class Search extends Command {
             this.error(error instanceof Error ? error.message : 'Failed to search packages');
         }
     }
-    displayResults(packages, hasMore) {
-        if (packages.length === 0) {
-            this.log(chalk.yellow('No packages found matching your query.'));
-            return;
-        }
-        this.log(`Found ${chalk.bold(packages.length)} package(s):`);
-        this.log();
-        for (const pkg of packages) {
-            const visibilityBadge = pkg.visibility === 'PUBLIC'
-                ? chalk.green('PUBLIC')
-                : chalk.yellow('PRIVATE');
-            this.log(`  ${chalk.cyan.bold(`${pkg.name}@${pkg.version}`)} ${visibilityBadge}`);
-            if (pkg.description) {
-                this.log(`    ${chalk.gray(pkg.description)}`);
-            }
-            this.log();
-        }
-        if (hasMore) {
-            this.log(chalk.dim('More results available. Use --limit to see more.'));
-        }
-    }
 }

package/dist/commands/undeploy/index.d.ts

@@ -6,8 +6,10 @@ export default class Undeploy extends Command {
         chdir: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         debug: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         workspace: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
+    private runInner;
     private undeployRemotely;
 }

package/dist/commands/undeploy/index.js

@@ -7,8 +7,9 @@ import { getBackend } from '../../backend/index.js';
 import { getExecutor } from '../../executor/index.js';
 import { getConfigManager } from '../../lib/config/index.js';
 import { getEnvManager } from '../../lib/env/index.js';
+import { getEphemeralToken, withEphemeralToken } from '../../lib/ephemeral-token.js';
 import { gitUtils } from '../../lib/git-utils.js';
-import { getLogger, getLogPath, isDebug, setDebug } from '../../lib/log.js';
+import { getDefaultLogger, getLogger, getLogPath, isDebug, setDebug } from '../../lib/log.js';
 import { getParameterManager } from '../../lib/parameter/index.js';
 import { getProfileFromWorkspace } from '../../lib/profile-utils.js';
 import { pollExecutorJob } from '../../lib/remote-job-utils.js';
@@ -35,6 +36,10 @@ export default class Undeploy extends Command {
             default: false,
             description: 'force local execution (skip remote executor)',
         }),
+        token: Flags.string({
+            description: 'Ephemeral cloud access token used for this invocation only. Held in memory; never written to the keychain or `~/.hereya/secrets/`. Takes precedence over the HEREYA_TOKEN environment variable.',
+            required: false,
+        }),
         workspace: Flags.string({
             char: 'w',
             description: 'name of the workspace to undeploy the packages for',
@@ -42,6 +47,17 @@ export default class Undeploy extends Command {
         }),
     };
     async run() {
+        const { flags } = await this.parse(Undeploy);
+        // Precedence: --token flag > HEREYA_TOKEN env var > keychain.
+        if (flags.token) {
+            if (process.env.HEREYA_TOKEN) {
+                getDefaultLogger().debug('[undeploy] --token flag overrides HEREYA_TOKEN environment variable.');
+            }
+            return withEphemeralToken(flags.token, () => this.runInner());
+        }
+        return this.runInner();
+    }
+    async runInner() {
         const { flags } = await this.parse(Undeploy);
         setDebug(flags.debug);
         const projectRootDir = path.resolve(flags.chdir || process.env.HEREYA_PROJECT_ROOT_DIR || process.cwd());
@@ -322,22 +338,41 @@ See ${getLogPath()} for more details`);
             this.error(cleanCheck.reason);
         }
         myLogger.log(ListrLogLevels.STARTED, `Undeploying ${input.workspace} via remote executor (branch: ${input.gitBranch})`);
-        // 2. Get cloud backend for job submission
-        const backendConfig = await loadBackendConfig();
-        if (!backendConfig.cloud) {
-            this.error('Remote undeployment requires cloud backend. Run `hereya login` first.');
+        // 2. Get cloud backend for job submission. If we are inside an ephemeral
+        // token scope (set by --token), use that token directly without touching
+        // the keychain or persisted credentials. Otherwise fall back to the
+        // standard "load credentials from disk + keychain" path.
+        const ephemeral = getEphemeralToken();
+        const resolvedWorkspaceName = resolveWorkspaceName(input.workspace, input.project);
+        let cloudBackend;
+        if (ephemeral) {
+            const url = ephemeral.cloudUrl
+                ?? process.env.HEREYA_CLOUD_URL
+                ?? (await loadBackendConfig()).cloud?.url
+                ?? 'https://cloud.hereya.dev';
+            cloudBackend = new CloudBackend({
+                accessToken: ephemeral.token,
+                clientId: '',
+                refreshToken: '',
+                url,
+            });
         }
-        const credentials = await getCloudCredentials(backendConfig.cloud.clientId);
-        if (!credentials) {
-            this.error('Cloud credentials not found. Run `hereya login` first.');
+        else {
+            const backendConfig = await loadBackendConfig();
+            if (!backendConfig.cloud) {
+                this.error('Remote undeployment requires cloud backend. Run `hereya login` first.');
+            }
+            const credentials = await getCloudCredentials(backendConfig.cloud.clientId);
+            if (!credentials) {
+                this.error('Cloud credentials not found. Run `hereya login` first.');
+            }
+            cloudBackend = new CloudBackend({
+                accessToken: credentials.accessToken,
+                clientId: backendConfig.cloud.clientId,
+                refreshToken: credentials.refreshToken,
+                url: backendConfig.cloud.url,
+            });
         }
-        const resolvedWorkspaceName = resolveWorkspaceName(input.workspace, input.project);
-        const cloudBackend = new CloudBackend({
-            accessToken: credentials.accessToken,
-            clientId: backendConfig.cloud.clientId,
-            refreshToken: credentials.refreshToken,
-            url: backendConfig.cloud.url,
-        });
         // 3. Submit undeploy job
         const submitResult = await cloudBackend.submitExecutorJob({
             payload: {

package/dist/commands/up/index.d.ts

@@ -7,7 +7,9 @@ export default class Up extends Command {
         debug: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         deploy: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         select: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+        token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
+    private runInner;
 }

package/dist/commands/up/index.js

@@ -4,7 +4,8 @@ import { getBackend } from '../../backend/index.js';
 import { getExecutorForWorkspace } from '../../executor/context.js';
 import { getConfigManager } from '../../lib/config/index.js';
 import { getEnvManager } from '../../lib/env/index.js';
-import { getLogger, getLogPath, isDebug, setDebug } from '../../lib/log.js';
+import { withEphemeralToken } from '../../lib/ephemeral-token.js';
+import { getDefaultLogger, getLogger, getLogPath, isDebug, setDebug } from '../../lib/log.js';
 import { getParameterManager } from '../../lib/parameter/index.js';
 import { getProfileFromWorkspace } from '../../lib/profile-utils.js';
 import { delay } from '../../lib/shell.js';
@@ -35,6 +36,10 @@ export default class Up extends Command {
             description: 'select the packages to provision',
             multiple: true,
         }),
+        token: Flags.string({
+            description: 'Ephemeral cloud access token used for this invocation only. Held in memory; never written to the keychain or `~/.hereya/secrets/`. Takes precedence over the HEREYA_TOKEN environment variable.',
+            required: false,
+        }),
         workspace: Flags.string({
             char: 'w',
             description: 'name of the workspace to install the packages for',
@@ -42,6 +47,17 @@ export default class Up extends Command {
         }),
     };
     async run() {
+        const { flags } = await this.parse(Up);
+        // Precedence: --token flag > HEREYA_TOKEN env var > keychain.
+        if (flags.token) {
+            if (process.env.HEREYA_TOKEN) {
+                getDefaultLogger().debug('[up] --token flag overrides HEREYA_TOKEN environment variable.');
+            }
+            return withEphemeralToken(flags.token, () => this.runInner());
+        }
+        return this.runInner();
+    }
+    async runInner() {
         const { flags } = await this.parse(Up);
         setDebug(flags.debug);
         const projectRootDir = flags.chdir || process.env.HEREYA_PROJECT_ROOT_DIR;

package/dist/commands/workspace/executor/install/index.d.ts

@@ -4,7 +4,9 @@ export default class WorkspaceExecutorInstall extends Command {
     static flags: {
         debug: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         workspace: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
+    private runInner;
 }

package/dist/commands/workspace/executor/install/index.js

@@ -3,7 +3,8 @@ import { Listr, ListrLogger, ListrLogLevels } from 'listr2';
 import { CloudBackend } from '../../../../backend/cloud/cloud-backend.js';
 import { getBackend } from '../../../../backend/index.js';
 import { getExecutor } from '../../../../executor/index.js';
-import { getLogger, getLogPath, isDebug, setDebug } from '../../../../lib/log.js';
+import { withEphemeralToken } from '../../../../lib/ephemeral-token.js';
+import { getDefaultLogger, getLogger, getLogPath, isDebug, setDebug } from '../../../../lib/log.js';
 import { delay } from '../../../../lib/shell.js';
 const DEFAULT_EXECUTOR_PACKAGE = 'hereya/remote-executor-aws';
 export default class WorkspaceExecutorInstall extends Command {
@@ -11,6 +12,10 @@ export default class WorkspaceExecutorInstall extends Command {
     static flags = {
         debug: Flags.boolean({ default: false, description: 'enable debug mode' }),
         force: Flags.boolean({ char: 'f', default: false, description: 'force reinstall even if executor is already installed' }),
+        token: Flags.string({
+            description: 'Ephemeral cloud access token used for this invocation only. Held in memory; never written to the keychain or `~/.hereya/secrets/`. Takes precedence over the HEREYA_TOKEN environment variable.',
+            required: false,
+        }),
         workspace: Flags.string({
             char: 'w',
             description: 'name of the workspace',
@@ -18,6 +23,17 @@ export default class WorkspaceExecutorInstall extends Command {
         }),
     };
     async run() {
+        const { flags } = await this.parse(WorkspaceExecutorInstall);
+        // Precedence: --token flag > HEREYA_TOKEN env var > keychain.
+        if (flags.token) {
+            if (process.env.HEREYA_TOKEN) {
+                getDefaultLogger().debug('[workspace executor install] --token flag overrides HEREYA_TOKEN environment variable.');
+            }
+            return withEphemeralToken(flags.token, () => this.runInner());
+        }
+        return this.runInner();
+    }
+    async runInner() {
         const { flags } = await this.parse(WorkspaceExecutorInstall);
         setDebug(flags.debug);
         const myLogger = new ListrLogger({ useIcons: false });

package/dist/commands/workspace/executor/token/index.d.ts

@@ -2,7 +2,9 @@ import { Command } from '@oclif/core';
 export default class WorkspaceExecutorToken extends Command {
     static description: string;
     static flags: {
+        token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         workspace: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
+    private runInner;
 }

package/dist/commands/workspace/executor/token/index.js

@@ -1,9 +1,15 @@
 import { Command, Flags } from '@oclif/core';
 import { CloudBackend } from '../../../../backend/cloud/cloud-backend.js';
 import { getBackend } from '../../../../backend/index.js';
+import { withEphemeralToken } from '../../../../lib/ephemeral-token.js';
+import { getDefaultLogger } from '../../../../lib/log.js';
 export default class WorkspaceExecutorToken extends Command {
     static description = 'Generate a workspace-scoped executor token for the remote executor';
     static flags = {
+        token: Flags.string({
+            description: 'Ephemeral cloud access token used for this invocation only. Held in memory; never written to the keychain or `~/.hereya/secrets/`. Takes precedence over the HEREYA_TOKEN environment variable.',
+            required: false,
+        }),
         workspace: Flags.string({
             char: 'w',
             description: 'name of the workspace',
@@ -11,6 +17,17 @@ export default class WorkspaceExecutorToken extends Command {
         }),
     };
     async run() {
+        const { flags } = await this.parse(WorkspaceExecutorToken);
+        // Precedence: --token flag > HEREYA_TOKEN env var > keychain.
+        if (flags.token) {
+            if (process.env.HEREYA_TOKEN) {
+                getDefaultLogger().debug('[workspace executor token] --token flag overrides HEREYA_TOKEN environment variable.');
+            }
+            return withEphemeralToken(flags.token, () => this.runInner());
+        }
+        return this.runInner();
+    }
+    async runInner() {
         const { flags } = await this.parse(WorkspaceExecutorToken);
         const backend = await getBackend();
         if (!(backend instanceof CloudBackend)) {

package/dist/commands/workspace/executor/uninstall/index.d.ts

@@ -3,7 +3,9 @@ export default class WorkspaceExecutorUninstall extends Command {
     static description: string;
     static flags: {
         debug: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         workspace: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
+    private runInner;
 }

package/dist/commands/workspace/executor/uninstall/index.js

@@ -3,13 +3,18 @@ import { Listr, ListrLogger, ListrLogLevels } from 'listr2';
 import { CloudBackend } from '../../../../backend/cloud/cloud-backend.js';
 import { getBackend } from '../../../../backend/index.js';
 import { getExecutor } from '../../../../executor/index.js';
-import { getLogger, getLogPath, isDebug, setDebug } from '../../../../lib/log.js';
+import { withEphemeralToken } from '../../../../lib/ephemeral-token.js';
+import { getDefaultLogger, getLogger, getLogPath, isDebug, setDebug } from '../../../../lib/log.js';
 import { delay } from '../../../../lib/shell.js';
 const DEFAULT_EXECUTOR_PACKAGE = 'hereya/remote-executor-aws';
 export default class WorkspaceExecutorUninstall extends Command {
     static description = 'Uninstall the remote executor from a workspace';
     static flags = {
         debug: Flags.boolean({ default: false, description: 'enable debug mode' }),
+        token: Flags.string({
+            description: 'Ephemeral cloud access token used for this invocation only. Held in memory; never written to the keychain or `~/.hereya/secrets/`. Takes precedence over the HEREYA_TOKEN environment variable.',
+            required: false,
+        }),
         workspace: Flags.string({
             char: 'w',
             description: 'name of the workspace',
@@ -17,6 +22,17 @@ export default class WorkspaceExecutorUninstall extends Command {
         }),
     };
     async run() {
+        const { flags } = await this.parse(WorkspaceExecutorUninstall);
+        // Precedence: --token flag > HEREYA_TOKEN env var > keychain.
+        if (flags.token) {
+            if (process.env.HEREYA_TOKEN) {
+                getDefaultLogger().debug('[workspace executor uninstall] --token flag overrides HEREYA_TOKEN environment variable.');
+            }
+            return withEphemeralToken(flags.token, () => this.runInner());
+        }
+        return this.runInner();
+    }
+    async runInner() {
         const { flags } = await this.parse(WorkspaceExecutorUninstall);
         setDebug(flags.debug);
         const myLogger = new ListrLogger({ useIcons: false });

package/dist/lib/ephemeral-token.d.ts

@@ -0,0 +1,38 @@
+/**
+ * In-memory context for an ephemeral, in-memory-only access token.
+ *
+ * This is used to support per-invocation tokens (e.g. minted by a separate
+ * MCP server) without persisting credentials to the user's keychain or
+ * `~/.hereya/secrets/`. Code that needs to read the active token (e.g. the
+ * cloud backend factory in `src/backend/index.ts`) calls
+ * {@link getEphemeralToken} and uses it directly as the bearer for outgoing
+ * cloud API calls. No exchange via `loginWithToken` happens — that path is
+ * intentionally avoided because it would mint a long-lived refresh token.
+ */
+export interface EphemeralTokenContext {
+    cloudUrl?: string;
+    token: string;
+}
+/**
+ * Returns the active ephemeral token context, or `undefined` if no
+ * `withEphemeralToken` scope is currently in flight.
+ */
+export declare function getEphemeralToken(): EphemeralTokenContext | undefined;
+/**
+ * Run `fn` inside an ephemeral-token scope. While `fn` is executing,
+ * `getEphemeralToken()` returns the supplied token (and optional cloudUrl).
+ *
+ * Critical guarantees:
+ * - The token is held in-memory only. It is NEVER passed to the secret
+ *   manager or written to disk.
+ * - After `fn` returns or throws, `getEphemeralToken()` returns `undefined`
+ *   again.
+ * - The cached backend in `src/backend/index.ts` is cleared before and after
+ *   the scope so that a stale, persisted-credential-backed CloudBackend is
+ *   never used while the scope is active, and the scope's in-memory backend
+ *   does not leak to subsequent code that expected the user's regular
+ *   credentials.
+ */
+export declare function withEphemeralToken<T>(token: string, fn: () => Promise<T>, options?: {
+    cloudUrl?: string;
+}): Promise<T>;

package/dist/lib/ephemeral-token.js

@@ -0,0 +1,36 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { clearBackend } from '../backend/index.js';
+const storage = new AsyncLocalStorage();
+/**
+ * Returns the active ephemeral token context, or `undefined` if no
+ * `withEphemeralToken` scope is currently in flight.
+ */
+export function getEphemeralToken() {
+    return storage.getStore();
+}
+/**
+ * Run `fn` inside an ephemeral-token scope. While `fn` is executing,
+ * `getEphemeralToken()` returns the supplied token (and optional cloudUrl).
+ *
+ * Critical guarantees:
+ * - The token is held in-memory only. It is NEVER passed to the secret
+ *   manager or written to disk.
+ * - After `fn` returns or throws, `getEphemeralToken()` returns `undefined`
+ *   again.
+ * - The cached backend in `src/backend/index.ts` is cleared before and after
+ *   the scope so that a stale, persisted-credential-backed CloudBackend is
+ *   never used while the scope is active, and the scope's in-memory backend
+ *   does not leak to subsequent code that expected the user's regular
+ *   credentials.
+ */
+export async function withEphemeralToken(token, fn, options) {
+    // Drop any cached backend so the next getBackend() call sees the ephemeral context.
+    clearBackend();
+    try {
+        return await storage.run({ cloudUrl: options?.cloudUrl, token }, fn);
+    }
+    finally {
+        // Drop the in-memory backend bound to the ephemeral token before yielding control.
+        clearBackend();
+    }
+}

package/dist/lib/package/index.d.ts

@@ -8,6 +8,18 @@ import { LocalPackageManager } from './local.js';
 export declare const githubPackageManager: PackageManager;
 export declare const localPackageManager: LocalPackageManager;
 export declare function getPackageManager(protocol: string, logger?: Logger): Promise<PackageManager>;
+/**
+ * Whether the cloud package registry should be consulted on this invocation.
+ *
+ * Returns true when either:
+ *  - the persisted backend type (from `~/.hereya/backend.yaml`) is `Cloud`, or
+ *  - an ephemeral `--token` is in scope (set via `withEphemeralToken`).
+ *
+ * The ephemeral-token branch is what makes `--token` work for fresh users who
+ * have never run `hereya login` — without it, the on-disk backend type stays
+ * `Local` and cloud-only packages fail to resolve.
+ */
+export declare function isCloudBackendActive(): Promise<boolean>;
 export declare function resolvePackage(input: ResolvePackageInput): Promise<ResolvePackageOutput>;
 export declare function getPackageCanonicalName(packageName: string): string;
 export declare function downloadPackage(pkgUrl: string, destPath: string): Promise<string>;

package/dist/lib/package/index.js

@@ -4,6 +4,7 @@ import { getCurrentBackendType } from '../../backend/config.js';
 import { BackendType, getBackend } from '../../backend/index.js';
 import { IacType } from '../../iac/common.js';
 import { InfrastructureType } from '../../infrastructure/common.js';
+import { getEphemeralToken } from '../ephemeral-token.js';
 import { CloudPackageManager } from './cloud.js';
 import { GitHubPackageManager } from './github.js';
 import { LocalPackageManager } from './local.js';
@@ -20,6 +21,23 @@ export async function getPackageManager(protocol, logger) {
     // Default to GitHub
     return githubPackageManager;
 }
+/**
+ * Whether the cloud package registry should be consulted on this invocation.
+ *
+ * Returns true when either:
+ *  - the persisted backend type (from `~/.hereya/backend.yaml`) is `Cloud`, or
+ *  - an ephemeral `--token` is in scope (set via `withEphemeralToken`).
+ *
+ * The ephemeral-token branch is what makes `--token` work for fresh users who
+ * have never run `hereya login` — without it, the on-disk backend type stays
+ * `Local` and cloud-only packages fail to resolve.
+ */
+export async function isCloudBackendActive() {
+    if (getEphemeralToken()) {
+        return true;
+    }
+    return (await getCurrentBackendType()) === BackendType.Cloud;
+}
 export async function resolvePackage(input) {
     // Parse package spec to extract name and version
     const { packageName, version } = parsePackageSpec(input.package);
@@ -31,23 +49,21 @@ export async function resolvePackage(input) {
         return { found: false, reason: 'Invalid package format. Package name cannot contain dots (.) nor double dashes (--)' };
     }
     const isLocal = packageName.startsWith('local/');
-    // Try cloud first if not local and backend is cloud
-    if (!isLocal) {
-        const backendType = await getCurrentBackendType();
-        if (backendType === BackendType.Cloud) {
-            const result = await tryCloudResolution(input);
-            if (result.found) {
-                return result; // Success
-            }
-            // Failed - check if we should fallback to GitHub or return the error
-            if (!packageName.includes('/')) {
-                // Simple package names can't fallback to GitHub, return the detailed error
-                return result;
-            }
-            // For owner/repo format, we can fallback to GitHub
-            input.logger?.debug(`Package ${packageName} not found in registry, trying GitHub...`);
-            input.logger?.debug(`Registry error: ${result.reason}`);
+    // Try cloud first if not local and backend is cloud (or an ephemeral
+    // --token is in scope, which acts as Cloud regardless of on-disk config).
+    if (!isLocal && await isCloudBackendActive()) {
+        const result = await tryCloudResolution(input);
+        if (result.found) {
+            return result; // Success
         }
+        // Failed - check if we should fallback to GitHub or return the error
+        if (!packageName.includes('/')) {
+            // Simple package names can't fallback to GitHub, return the detailed error
+            return result;
+        }
+        // For owner/repo format, we can fallback to GitHub
+        input.logger?.debug(`Package ${packageName} not found in registry, trying GitHub...`);
+        input.logger?.debug(`Registry error: ${result.reason}`);
     }
     // Determine protocol for standard resolution
     const protocol = isLocal ? 'local' : '';
@@ -63,12 +79,10 @@ export async function downloadPackage(pkgUrl, destPath) {
     if (pkgUrl.startsWith('local/')) {
         protocol = 'local';
     }
-    else if (pkgUrl.includes('#')) {
-        // Registry package URLs contain commit SHA
-        const backendType = await getCurrentBackendType();
-        if (backendType === BackendType.Cloud) {
-            protocol = 'cloud';
-        }
+    else if (pkgUrl.includes('#') && await isCloudBackendActive()) {
+        // Registry package URLs contain commit SHA. Cloud branch fires when
+        // backend.yaml says Cloud OR an ephemeral --token is in scope.
+        protocol = 'cloud';
     }
     // Otherwise defaults to GitHub
     const packageManager = await getPackageManager(protocol);