handoff-app 2.0.0-7 → 2.0.0-9

package/src/app/pages/account/tokens.tsx

@@ -120,7 +120,9 @@ function RegistryTokensPage() {
         <Card>
           <CardHeader>
             <CardTitle>Create access token</CardTitle>
-            <CardDescription>Use tokens for CI or integrations that cannot complete the browser device login.</CardDescription>
+            <CardDescription>
+              Connect a workspace, a CI job, or an integration. This is the same credential the CLI login issues.
+            </CardDescription>
           </CardHeader>
           <form onSubmit={create}>
             <CardContent className="space-y-4">

package/src/app-builder/build.ts

@@ -443,13 +443,21 @@ After migrations and deployment, open \`/install\` immediately and create the in
 The installer verifies the deployment but never changes the schema. An exposed, uninstalled registry
 can be claimed by its first visitor, so do not leave this step unattended.
 
-Once installation completes, sign in and authorize a workspace:
+Once installation completes, sign in and authorize a workspace. Either approve the CLI in the
+browser:
 
 \`\`\`bash
 handoff-app login --url https://registry.example.com
 \`\`\`
 
-The browser approval issues a revocable, user-owned credential. The former
+or create a token under Account > Access tokens and set it in the workspace environment:
+
+\`\`\`bash
+HANDOFF_REGISTRY_URL=https://registry.example.com
+HANDOFF_REGISTRY_ACCESS_TOKEN=hnd_…
+\`\`\`
+
+Both produce the same revocable, user-owned credential. The former
 \`HANDOFF_REGISTRY_API_TOKEN\` fixed server secret is no longer accepted.
 
 ## Run it (self-hosting)

package/src/app-builder/client-config.ts

@@ -5,7 +5,7 @@ import { getClientConfig, isMcpEnabled } from '../config';
 import { resolveAssetStorageFromConfig } from '../registry/asset-storage/resolve';
 import { resolveAuthenticatedRegistryConnection } from '../registry/connection';
 import { resolveDatabaseUrlEnv, resolveRegistryDriver } from '../registry/db/driver';
-import type { Config, RuntimeMode } from '../types/config';
+import type { ResolvedConfig, RuntimeMode } from '../types/config';
 import { getAppPath } from './paths';
 
 /**
@@ -53,7 +53,7 @@ export const generateTokensApi = async (handoff: Handoff) => {
  * var) to back the registry-mode docs read API. These are non-secret — the connection-string value
  * itself is never persisted, only resolved from the env var at request time.
  */
-const buildServerRuntimeConfig = (config: Config, modeOverride?: RuntimeMode) => {
+const buildServerRuntimeConfig = (config: ResolvedConfig, modeOverride?: RuntimeMode) => {
   const assetStorage = resolveAssetStorageFromConfig(config);
   return {
     mode: modeOverride ?? config?.runtime?.mode ?? 'workspace',
@@ -100,7 +100,9 @@ export const persistClientConfig = async (handoff: Handoff, options: PersistClie
   // registry URL resolves — from config/env or a saved device login — so `login` alone surfaces
   // the publish/checkout UI without also requiring HANDOFF_REGISTRY_URL.
   const connected =
-    mode === 'registry' ? false : Boolean((await resolveAuthenticatedRegistryConnection(handoff.config, handoff.workingPath)).url);
+    mode === 'registry'
+      ? false
+      : Boolean((await resolveAuthenticatedRegistryConnection(handoff.config, handoff.workingPath, handoff.getProfile())).url);
   clientConfig.runtime = { ...clientConfig.runtime, mode, connected };
 
   await fs.writeJson(path.resolve(appPath, 'client.config.json'), { config: clientConfig }, { spaces: 2 });

package/src/app-builder/watchers.ts

@@ -250,21 +250,31 @@ export const watchRuntimeConfiguration = (handoff: Handoff, state: WatcherState)
               const handle =
                 entryBefore && strategy ? strategy.capture(handoff, entryBefore.entityId) : undefined;
 
-              handoff.reload();
-              await persistClientConfig(handoff);
+              let reloadFailed = false;
+              try {
+                handoff.reload();
+                await persistClientConfig(handoff);
+              } catch (e) {
+                // A failed reload leaves the last config that loaded on the instance, so the
+                // re-arm below still names the file that just broke. Without it the file drops
+                // out of the watch set - chokidar stops tracking a watched file once it is
+                // deleted - and a later valid save is never seen.
+                reloadFailed = true;
+                Logger.error('Error reloading runtime configuration:', e);
+              }
+
               watchRuntimeComponents(handoff, state, getRuntimeComponentsPathsToWatch(handoff));
               watchRuntimeConfiguration(handoff, state);
 
-              const entryAfter = handoff.getConfigFileEntry(changedFile);
+              if (reloadFailed) {
+                return;
+              }
 
-              const normalizedChanged = normalizePathForCompare(changedFile);
-              const normalizedMainConfig = handoff.getMainConfigFilePath()
-                ? normalizePathForCompare(handoff.getMainConfigFilePath() as string)
-                : undefined;
+              const entryAfter = handoff.getConfigFileEntry(changedFile);
 
               const kindChanged = !!entryBefore && !!entryAfter && entryBefore.kind !== entryAfter.kind;
 
-              if (normalizedMainConfig && normalizedChanged === normalizedMainConfig) {
+              if (handoff.isMainConfigFile(changedFile)) {
                 await processComponents(handoff);
               } else if (kindChanged) {
                 // The declaration switched between an implementation and a composition. A targeted

package/src/cache/build-cache.ts

@@ -48,7 +48,11 @@ export interface BuildCache {
  * Gets the path to the build cache file
  */
 export function getCachePath(handoff: Handoff): string {
-  return path.resolve(handoff.modulePath, '.handoff', handoff.getProjectId(), '.cache', 'build-cache.json');
+  // Two profiles share one project id and can build different output, so the profile has to name
+  // the cache file. One shared cache would serve the other profile's components.
+  const profile = handoff.getProfile();
+  const fileName = profile ? `build-cache.${profile}.json` : 'build-cache.json';
+  return path.resolve(handoff.modulePath, '.handoff', handoff.getProjectId(), '.cache', fileName);
 }
 
 /**

package/src/catalog/README.md

@@ -30,6 +30,9 @@ owns `fromCSF`, because CSF is a source format of React rather than a framework.
 The renderer entry points call `createCatalogItem` with their renderer. The pattern entry point calls it without a renderer.
 `define.ts` handles the shared `implementation` forms: a helper's `{ format, file }`, a file path, or an imported component.
 
+An entry point re-exports only the preview shape its renderer honors: `react.ts` exports `CatalogPreview` with `render`,
+`handlebars.ts` narrows it to reject `render`, and `pattern.ts` exports neither.
+
 A new renderer needs:
 
 - A `RENDERERS` row in `renderers.ts`

package/src/catalog/normalize.ts

@@ -101,6 +101,8 @@ export const normalizeCatalogItem = (moduleExports: Record<string, unknown>, opt
   entries[entryKey] = path.resolve(directory, source.file);
   // Existing builders consume template as the primary build input for every renderer.
   entries.template = entries[entryKey];
+  // The renderer and the hydration bundle both read a preview `render` from the declaration.
+  if (options.declarationPath) entries.declaration = options.declarationPath;
   // A wrong renderer builds a broken preview without failing on its own, so a mismatch is fatal.
   // `config/runtime.ts` turns the throw into a skipped item that retries on the next save.
   const claim = sourceForFile(source.file);

package/src/catalog/previews.ts

@@ -5,15 +5,17 @@ import type { CatalogPreview } from './types';
 
 /**
  * A declaration module exports more than previews: the item itself, the implementation it
- * re-exports, helper values. Accept only a plain object that owns `args` or `name`, so an exported
- * component or helper is never mistaken for a preview.
+ * re-exports, helper values. Accept only a plain object that owns one of the preview fields, so an
+ * exported component or helper is never mistaken for a preview.
  *
  * `getCsfStoryEntries` does not fit here: on a CSF file every named export is a story, and on a
  * declaration file it is not.
  */
+const PREVIEW_KEYS = ['args', 'name', 'render'] as const;
+
 const isPreviewDeclaration = (value: unknown): boolean => {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
-  return Object.prototype.hasOwnProperty.call(value, 'args') || Object.prototype.hasOwnProperty.call(value, 'name');
+  return PREVIEW_KEYS.some((key) => Object.prototype.hasOwnProperty.call(value, key));
 };
 
 /** Matches an exported binding, an export list, or a CommonJS export assignment. */
@@ -104,6 +106,7 @@ export const createCatalogPreviews = (
       values: { ...(preview.args ?? {}) },
       url: preview.url ?? '',
       ...(preview.usage ? { usage: preview.usage } : {}),
+      ...(typeof preview.render === 'function' ? { render: preview.render as OptionalPreviewRender['render'] } : {}),
     };
   }
 

package/src/catalog/types.ts

@@ -53,6 +53,14 @@ export type CatalogPreview<TArgs = Record<string, unknown>> = {
   args?: TArgs;
   usage?: string;
   url?: string;
+  /**
+   * Renders this preview in place of the implementation, for props it cannot carry as data: an icon
+   * component, a callback, JSX children, or state the preview owns.
+   *
+   * Rendered as a component with `args`, so it can use hooks. The item still documents the
+   * implementation, so a wrapper never becomes the published API.
+   */
+  render?: (args: TArgs) => unknown;
 };
 
 /**

package/src/cli/auth/device.ts

@@ -31,6 +31,8 @@ interface Envelope<T> {
 
 export interface LoginOptions {
   openBrowser?: boolean;
+  /** Profile the issued credential is saved under. Omitted, it is the default profile. */
+  profile?: string;
 }
 
 const sleep = (milliseconds: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, milliseconds));
@@ -71,7 +73,10 @@ const shouldOpenBrowser = (options: LoginOptions): boolean => {
 const positiveNumberOr = (value: unknown, fallback: number): number =>
   typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
 
-/** Complete the device grant and persist the one-time plaintext access token for this workspace. */
+/**
+ * Complete the device grant and persist the one-time plaintext access token for this workspace,
+ * under the selected profile.
+ */
 export const loginWithDevice = async (workingPath: string, remoteUrl: string, options: LoginOptions = {}): Promise<CliAuth> => {
   const baseUrl = normalizeRegistryUrl(remoteUrl);
   let deviceResponse: Response;
@@ -98,7 +103,7 @@ export const loginWithDevice = async (workingPath: string, remoteUrl: string, op
   const verificationUrl = assertRegistryOriginUrl(
     baseUrl,
     device.verification_uri_complete ||
-      `${device.verification_uri}${device.verification_uri.includes('?') ? '&' : '?'}user_code=${encodeURIComponent(device.user_code)}`,
+      `${device.verification_uri}${device.verification_uri.includes('?') ? '&' : '?'}user_code=${encodeURIComponent(device.user_code)}`
   );
 
   Logger.log('');
@@ -142,7 +147,7 @@ export const loginWithDevice = async (workingPath: string, remoteUrl: string, op
         accessToken: token.access_token,
         expiresAtMs: Date.now() + expiresIn * 1000,
       };
-      await writeCliAuth(workingPath, auth);
+      await writeCliAuth(workingPath, auth, options.profile);
       return auth;
     }
 

package/src/cli/auth/store.ts

@@ -9,9 +9,17 @@ export interface CliAuth {
   expiresAtMs: number;
 }
 
+/** Name a login is saved under when no profile is selected. */
+export const DEFAULT_LOGIN_PROFILE = 'default';
+
 const AUTH_DIRECTORY = '.handoff';
 const AUTH_FILE = 'cli-auth.json';
 
+/** The credential file: one login per profile name, so a workspace can hold several registries. */
+interface CliAuthFile {
+  logins: Record<string, CliAuth>;
+}
+
 /**
  * Canonicalize a registry URL for both HTTP requests and exact credential matching.
  * Base paths are retained; query strings, fragments, credentials, and trailing slashes are not.
@@ -58,38 +66,67 @@ export const assertRegistryOriginUrl = (baseUrl: string, candidate: string): str
 
 export const cliAuthFilePath = (workingPath: string): string => path.resolve(workingPath, AUTH_DIRECTORY, AUTH_FILE);
 
-const isCliAuth = (value: unknown): value is CliAuth => {
-  if (!value || typeof value !== 'object') return false;
+/** An invalid or partial entry reads as no login, so one bad entry cannot hide the others. */
+const toCliAuth = (value: unknown): CliAuth | null => {
+  if (!value || typeof value !== 'object') return null;
   const auth = value as Partial<CliAuth>;
-  return (
-    typeof auth.remoteUrl === 'string' &&
-    typeof auth.accessToken === 'string' &&
-    auth.accessToken.length > 0 &&
-    typeof auth.expiresAtMs === 'number' &&
-    Number.isFinite(auth.expiresAtMs)
-  );
-};
+  if (typeof auth.remoteUrl !== 'string') return null;
+  if (typeof auth.accessToken !== 'string' || auth.accessToken.length === 0) return null;
+  if (typeof auth.expiresAtMs !== 'number' || !Number.isFinite(auth.expiresAtMs)) return null;
 
-/** Invalid or partial credential files are treated as unauthenticated. */
-export const readCliAuth = async (workingPath: string): Promise<CliAuth | null> => {
   try {
-    const value = (await fs.readJson(cliAuthFilePath(workingPath))) as unknown;
-    if (!isCliAuth(value)) return null;
-    return { ...value, remoteUrl: normalizeRegistryUrl(value.remoteUrl) };
+    return { remoteUrl: normalizeRegistryUrl(auth.remoteUrl), accessToken: auth.accessToken, expiresAtMs: auth.expiresAtMs };
   } catch {
     return null;
   }
 };
 
+const toLogins = (value: unknown): Record<string, CliAuth> => {
+  const logins = (value as Partial<CliAuthFile> | null)?.logins;
+  if (!logins || typeof logins !== 'object') return {};
+
+  const result: Record<string, CliAuth> = {};
+  for (const [profile, entry] of Object.entries(logins as Record<string, unknown>)) {
+    const auth = toCliAuth(entry);
+    if (auth) result[profile] = auth;
+  }
+  return result;
+};
+
+/** Every saved login, keyed by profile name. A missing or unreadable file reads as no logins. */
+export const readCliLogins = async (workingPath: string): Promise<Record<string, CliAuth>> => {
+  try {
+    return toLogins((await fs.readJson(cliAuthFilePath(workingPath))) as unknown);
+  } catch {
+    return {};
+  }
+};
+
+/** The login saved under one profile name. Never falls back to another profile. */
+export const readCliAuth = async (workingPath: string, profile: string = DEFAULT_LOGIN_PROFILE): Promise<CliAuth | null> =>
+  (await readCliLogins(workingPath))[profile] ?? null;
+
+/**
+ * Profile names that have a saved login. Synchronous because config loading is, and the loader needs
+ * these names to decide whether a selected profile resolves.
+ */
+export const loginProfileNames = (workingPath: string): string[] => {
+  try {
+    return Object.keys(toLogins(fs.readJsonSync(cliAuthFilePath(workingPath)) as unknown));
+  } catch {
+    return [];
+  }
+};
+
 /**
  * Atomically replace the credential file. Restrictive permissions are best-effort on platforms
  * whose filesystems do not support POSIX modes.
  */
-export const writeCliAuth = async (workingPath: string, auth: CliAuth): Promise<void> => {
+const writeCliLogins = async (workingPath: string, logins: Record<string, CliAuth>): Promise<void> => {
   const filePath = cliAuthFilePath(workingPath);
   const directory = path.dirname(filePath);
   const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
-  const value: CliAuth = { ...auth, remoteUrl: normalizeRegistryUrl(auth.remoteUrl) };
+  const value: CliAuthFile = { logins };
 
   await fs.ensureDir(directory, 0o700);
   try {
@@ -117,7 +154,27 @@ export const writeCliAuth = async (workingPath: string, auth: CliAuth): Promise<
   }
 };
 
-export const clearCliAuth = async (workingPath: string): Promise<void> => {
+/** Save the login for one profile and leave the other profiles in place. */
+export const writeCliAuth = async (workingPath: string, auth: CliAuth, profile: string = DEFAULT_LOGIN_PROFILE): Promise<void> => {
+  const logins = await readCliLogins(workingPath);
+  logins[profile] = { ...auth, remoteUrl: normalizeRegistryUrl(auth.remoteUrl) };
+  await writeCliLogins(workingPath, logins);
+};
+
+/** Remove the login for one profile, and the file itself once no login is left. */
+export const clearCliAuth = async (workingPath: string, profile: string = DEFAULT_LOGIN_PROFILE): Promise<void> => {
+  const logins = await readCliLogins(workingPath);
+  delete logins[profile];
+
+  if (Object.keys(logins).length === 0) {
+    await clearAllCliAuth(workingPath);
+    return;
+  }
+  await writeCliLogins(workingPath, logins);
+};
+
+/** Remove every saved login. */
+export const clearAllCliAuth = async (workingPath: string): Promise<void> => {
   const filePath = cliAuthFilePath(workingPath);
   if (await fs.pathExists(filePath)) {
     await fs.remove(filePath);

package/src/commands/login/index.ts

@@ -1,6 +1,6 @@
 import { CommandModule } from 'yargs';
 import { loginWithDevice } from '../../cli/auth/device';
-import { cliAuthFilePath } from '../../cli/auth/store';
+import { cliAuthFilePath, DEFAULT_LOGIN_PROFILE, readCliAuth } from '../../cli/auth/store';
 import { resolveRegistryConnection } from '../../registry/connection';
 import { Logger } from '../../utils/logger';
 import { SharedArgs } from '../types';
@@ -11,6 +11,11 @@ export interface LoginArgs extends SharedArgs {
   browser?: boolean;
 }
 
+/**
+ * Saves one registry credential per profile, so a workspace can hold a login for every registry it
+ * publishes to. The name is independent of the config profiles, and `login` is the one command that
+ * accepts a profile nothing else knows yet.
+ */
 const command: CommandModule<{}, LoginArgs> = {
   command: 'login',
   describe: 'Sign in to a registry using browser device authorization',
@@ -26,17 +31,26 @@ const command: CommandModule<{}, LoginArgs> = {
         describe: 'Open the approval URL in the default browser (disable with --no-browser)',
       }),
   handler: async (args: LoginArgs) => {
-    const handoff = createHandoff(args);
+    const handoff = createHandoff(args, { profileWithoutConfig: 'any' });
+    const profile = handoff.getProfile() ?? DEFAULT_LOGIN_PROFILE;
     try {
       const configured = resolveRegistryConnection(handoff.config);
-      const remoteUrl = args.url?.trim() || configured.url;
+      // Resolved in the order publish and checkout use, so a login always targets the registry those
+      // commands would reach.
+      const saved = await readCliAuth(handoff.workingPath, profile);
+      const remoteUrl = args.url?.trim() || configured.url || saved?.remoteUrl;
       if (!remoteUrl) {
         throw new Error(`Pass --url <registry-url>, configure runtime.registryConnection.url, or set "${configured.urlEnv}".`);
       }
 
-      await loginWithDevice(handoff.workingPath, remoteUrl, { openBrowser: args.browser !== false });
-      Logger.success(`Logged in. Credentials saved to ${cliAuthFilePath(handoff.workingPath)}.`);
-      Logger.info('Publish and checkout commands will use this login for the matching registry URL.');
+      await loginWithDevice(handoff.workingPath, remoteUrl, { openBrowser: args.browser !== false, profile });
+      const named = profile === DEFAULT_LOGIN_PROFILE ? '' : ` under profile "${profile}"`;
+      Logger.success(`Logged in. Credentials saved to ${cliAuthFilePath(handoff.workingPath)}${named}.`);
+      Logger.info(
+        profile === DEFAULT_LOGIN_PROFILE
+          ? 'Publish and checkout commands will use this login for the matching registry URL.'
+          : `Publish and checkout commands will use this login when they run with --profile ${profile}.`
+      );
     } catch (error) {
       Logger.error(error instanceof Error ? error.message : String(error));
       process.exitCode = 1;

package/src/commands/logout/index.ts

@@ -1,45 +1,99 @@
 import { CommandModule } from 'yargs';
 import { revokeAccessToken } from '../../cli/auth/device';
-import { clearCliAuth, cliAuthFilePath, cliAuthMatchesRegistry, normalizeRegistryUrl, readCliAuth } from '../../cli/auth/store';
+import {
+  type CliAuth,
+  clearAllCliAuth,
+  clearCliAuth,
+  cliAuthFilePath,
+  cliAuthMatchesRegistry,
+  DEFAULT_LOGIN_PROFILE,
+  normalizeRegistryUrl,
+  readCliAuth,
+  readCliLogins,
+} from '../../cli/auth/store';
 import { Logger } from '../../utils/logger';
 import { SharedArgs } from '../types';
 import { createHandoff, getSharedOptions } from '../utils';
 
 export interface LogoutArgs extends SharedArgs {
   url?: string;
+  all?: boolean;
 }
 
+/** Remote revocation is best effort: the local credential goes either way. */
+const revoke = async (auth: CliAuth): Promise<void> => {
+  try {
+    await revokeAccessToken(auth);
+  } catch (error) {
+    Logger.warn(
+      `Could not revoke the registry token for ${auth.remoteUrl} (${error instanceof Error ? error.message : String(error)}). ` +
+        'It will still be removed from this workspace.'
+    );
+  }
+};
+
+/**
+ * `handoff-app logout` removes the login of the selected profile, leaving every other profile signed
+ * in. `--all` removes them all.
+ */
 const command: CommandModule<{}, LogoutArgs> = {
   command: 'logout',
   describe: 'Revoke and remove saved registry credentials',
   builder: (yargs) =>
-    getSharedOptions(yargs).option('url', {
-      type: 'string',
-      describe: 'Revoke credentials only when they belong to this exact registry URL',
-    }),
+    getSharedOptions(yargs)
+      .option('url', {
+        type: 'string',
+        describe: 'Revoke credentials only when they belong to this exact registry URL',
+      })
+      .option('all', {
+        type: 'boolean',
+        describe: 'Revoke and remove the saved credentials for every profile',
+      })
+      .conflicts('all', 'url'),
   handler: async (args: LogoutArgs) => {
-    const handoff = createHandoff(args);
-    const auth = await readCliAuth(handoff.workingPath);
-    if (args.url && auth && !cliAuthMatchesRegistry(auth, args.url)) {
-      Logger.error(`The saved login belongs to ${auth.remoteUrl}, not ${normalizeRegistryUrl(args.url)}. No credentials were changed.`);
-      process.exitCode = 1;
-      return;
-    }
+    const handoff = createHandoff(args, { profileWithoutConfig: 'saved-login' });
+    const profile = handoff.getProfile() ?? DEFAULT_LOGIN_PROFILE;
+    const named = profile === DEFAULT_LOGIN_PROFILE ? '' : ` for profile "${profile}"`;
+
+    if (args.all) {
+      const logins = await readCliLogins(handoff.workingPath);
+      const names = Object.keys(logins);
+      if (!names.length) {
+        Logger.info('No saved logins.');
+        return;
+      }
 
-    if (auth) {
+      for (const name of names) {
+        await revoke(logins[name]);
+      }
       try {
-        await revokeAccessToken(auth);
+        await clearAllCliAuth(handoff.workingPath);
+        Logger.success(`Logged out of every saved profile: ${names.join(', ')}. Removed ${cliAuthFilePath(handoff.workingPath)}.`);
       } catch (error) {
-        Logger.warn(
-          `Could not revoke the registry token remotely (${error instanceof Error ? error.message : String(error)}). ` +
-            'It will still be removed from this workspace.'
-        );
+        Logger.error(`Could not remove saved credentials: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
       }
+      return;
+    }
+
+    const auth = await readCliAuth(handoff.workingPath, profile);
+    if (!auth) {
+      Logger.info(`No saved login${named}.`);
+      return;
     }
+    if (args.url && !cliAuthMatchesRegistry(auth, args.url)) {
+      Logger.error(
+        `The saved login${named} belongs to ${auth.remoteUrl}, not ${normalizeRegistryUrl(args.url)}. No credentials were changed.`
+      );
+      process.exitCode = 1;
+      return;
+    }
+
+    await revoke(auth);
 
     try {
-      await clearCliAuth(handoff.workingPath);
-      Logger.success(`Logged out. Removed ${cliAuthFilePath(handoff.workingPath)}.`);
+      await clearCliAuth(handoff.workingPath, profile);
+      Logger.success(`Logged out of ${auth.remoteUrl}${named}. Removed the saved credentials.`);
     } catch (error) {
       Logger.error(`Could not remove saved credentials: ${error instanceof Error ? error.message : String(error)}`);
       process.exitCode = 1;

package/src/commands/types.ts

@@ -3,6 +3,8 @@ import { Arguments } from 'yargs';
 export interface SharedArgs extends Arguments {
   /** Explicit config file, replacing the usual `handoff.config.*` lookup. */
   config?: string;
+  /** Config profile merged onto the base config; overrides `HANDOFF_PROFILE`. */
+  profile?: string;
   force?: boolean;
   debug?: boolean;
   /**

package/src/commands/utils.ts

@@ -1,5 +1,5 @@
 import { Argv } from 'yargs';
-import Handoff from '../';
+import Handoff, { HandoffOptions } from '../';
 import { REGISTRY_ENTITY_KINDS } from '../registry/content-kinds';
 import { Logger } from '../utils/logger';
 import { SharedArgs } from './types';
@@ -20,22 +20,26 @@ export type RegistryTargetKind = (typeof REGISTRY_TARGET_KINDS)[number];
 export const COMPAT_TARGET_KINDS = [...REGISTRY_ENTITY_KINDS, 'all'] as const;
 export type CompatTargetKind = (typeof COMPAT_TARGET_KINDS)[number];
 
-export const createHandoff = (args: SharedArgs): Handoff =>
+export const createHandoff = (args: SharedArgs, options: Pick<HandoffOptions, 'profileWithoutConfig'> = {}): Handoff =>
   new Handoff({
     debug: args.debug,
     force: args.force,
     configPath: args.config,
+    profile: args.profile,
     dryRun: args.dryRun,
     // yargs gives `--no-build` as `build: false`; anything else leaves the build in place.
     skipBuild: args.build === false,
+    ...options,
   });
 
 /**
- * Run a registry command against a fresh Handoff. Registry failures are the user's to act on, so they
- * surface as one actionable line and a non-zero exit rather than a stack trace.
+ * Run a registry command against a fresh Handoff. A selected profile may name a saved login instead
+ * of a config file, because here the profile selects the registry. Registry failures are the
+ * user's to act on, so they surface as one actionable line and a non-zero exit rather than a stack
+ * trace.
  */
 export const runRegistryCommand = async (args: SharedArgs, run: (handoff: Handoff) => Promise<unknown>): Promise<void> => {
-  const handoff = createHandoff(args);
+  const handoff = createHandoff(args, { profileWithoutConfig: 'saved-login' });
   try {
     await run(handoff);
   } catch (error) {
@@ -61,6 +65,11 @@ export const getSharedOptions = (yargs: Argv) => {
       type: 'boolean',
       description: 'Enable debug mode',
     },
+    profile: {
+      type: 'string',
+      description:
+        'Config profile merged onto the base config (handoff.config.<profile>.*), and the saved login that registry commands use; overrides HANDOFF_PROFILE',
+    },
   });
 };