@agentuity/cli 1.0.1 → 1.0.3

package/src/cli.ts

@@ -14,20 +14,36 @@ import type {
 	GlobalOptions,
 } from './types';
 import { showBanner, generateBanner } from './banner';
-import { requireAuth, optionalAuth, requireOrg, optionalOrg as selectOptionalOrg } from './auth';
+import { getExecutingAgent } from './agent-detection';
+import {
+	requireAuth,
+	optionalAuth,
+	requireOrg,
+	optionalOrg as selectOptionalOrg,
+	hasPrefixedResourceId,
+	resolveOrgIdWithoutPrompt,
+} from './auth';
 import { type RegionList, ValidationOutputError } from '@agentuity/server';
 import { fetchRegionsWithCache } from './regions';
 import enquirer from 'enquirer';
 import * as tui from './tui';
 import { parseArgsSchema, parseOptionsSchema, buildValidationInputAsync } from './schema-parser';
-import { defaultProfileName, loadProjectConfig } from './config';
+import { defaultProfileName, loadProjectConfig, saveProjectId, saveRegion } from './config';
 import { APIClient, getAPIBaseURL, getAppBaseURL, type APIClient as APIClientType } from './api';
 import { ErrorCode, ExitCode, createError, exitWithError } from './errors';
 import { getCommand } from './command-prefix';
 import { isValidateMode, outputValidation, type ValidationResult } from './output';
 import { StructuredError } from '@agentuity/core';
 import { setProgram } from './program-ref';
-import { getCachedProject, setCachedProject } from './cache';
+import { generateIntroPrompt } from './cmd/ai/intro';
+import {
+	getCachedProject,
+	getResourceInfo,
+	setCachedProject,
+	type ResourceType,
+	hasAgentSeenIntro,
+	markAgentIntroSeen,
+} from './cache';
 
 /**
  * Check if an error is a CLI input validation error (Zod error from schema parsing),
@@ -124,12 +140,12 @@ async function executeOrValidate(
 		};
 		outputValidation(result, ctx.options);
 	} else if (handler) {
-		// Render "View on the web" link before normal execution
-		maybeRenderWebLink(ctx, webUrl);
-
 		// Normal execution
 		const result = await handler(ctx);
 
+		// Render "View on the web" link after successful execution (not shown on errors)
+		maybeRenderWebLink(ctx, webUrl);
+
 		// If --json flag is set
 		if (ctx.options.json) {
 			// If command has a response schema but returned nothing, that's an error
@@ -455,6 +471,10 @@ async function promptProjectSelection(baseCtx: CommandContext): Promise<ProjectC
 		return null;
 	}
 
+	if (selectedProject.id !== config?.preferences?.projectId) {
+		await saveProjectId(selectedProject.id);
+	}
+
 	// Convert to ProjectConfig format
 	return {
 		projectId: selectedProject.id,
@@ -485,6 +505,11 @@ export async function createCLI(version: string): Promise<Command> {
 			'Use a specific organization when performing operations',
 			process.env.AGENTUITY_CLOUD_ORG_ID
 		)
+		.option(
+			'--project-id <id>',
+			'Use a specific project when performing operations (AGENTUITY_CLOUD_PROJECT_ID)',
+			process.env.AGENTUITY_CLOUD_PROJECT_ID
+		)
 		.option('--color-scheme <scheme>', 'Color scheme: light or dark')
 		.option('--color <mode>', 'Color output: auto, always, never', 'auto')
 		.option('--error-format <format>', 'Error output format: json or text', 'text')
@@ -493,7 +518,8 @@ export async function createCLI(version: string): Promise<Command> {
 		.option('--no-progress', 'Disable progress indicators', false)
 		.option('--explain', 'Show what the command would do without executing', false)
 		.option('--dry-run', 'Execute command without making changes', false)
-		.option('--validate', 'Validate arguments and options without executing', false);
+		.option('--validate', 'Validate arguments and options without executing', false)
+		.option('--ai-help', 'Show AI-optimized help in dashdash format', false);
 
 	const skipVersionCheckOption = program.createOption(
 		'--skip-version-check',
@@ -502,6 +528,13 @@ export async function createCLI(version: string): Promise<Command> {
 	skipVersionCheckOption.hideHelp();
 	program.addOption(skipVersionCheckOption);
 
+	const profileOption = program.createOption(
+		'--profile <name>',
+		'Override the default profile (takes precedence over AGENTUITY_PROFILE env var)'
+	);
+	profileOption.hideHelp();
+	program.addOption(profileOption);
+
 	program.action(() => {
 		program.help();
 	});
@@ -609,13 +642,34 @@ export async function createCLI(version: string): Promise<Command> {
 			// Format each section (show banner for root command)
 			let output = '';
 
+			// Show intro for first-time agents (before normal help output)
+			// AGENTUITY_SHOW_INTRO=1 forces showing the intro (useful for testing)
+			const agent = getExecutingAgent();
+			const forceShowIntro = process.env.AGENTUITY_SHOW_INTRO === '1';
+			const hasSeenIntro = agent ? hasAgentSeenIntro(agent) : true;
+
+			if (agent && (forceShowIntro || !hasSeenIntro)) {
+				// Only mark as seen if this is their first time (not on forced re-shows)
+				if (!hasSeenIntro) {
+					markAgentIntroSeen(agent);
+				}
+
+				const separator = '='.repeat(79);
+				output += `${separator}\n\n`;
+				output += generateIntroPrompt(agent);
+				output += `\n${separator}\n\n`;
+			}
+
 			// Show banner (full for root, compact for subcommands)
+			// Skip banner when running from an AI coding agent
 			// eslint-disable-next-line @typescript-eslint/no-explicit-any
 			const isRootCommand = !(cmd as any).parent;
-			if (isRootCommand) {
-				output += `${generateBanner(version)}\n\n`;
-			} else {
-				output += `${generateBanner(version, true)}\n`;
+			if (!agent) {
+				if (isRootCommand) {
+					output += `${generateBanner(version)}\n\n`;
+				} else {
+					output += `${generateBanner(version, true)}\n`;
+				}
 			}
 
 			// Description
@@ -669,15 +723,19 @@ export async function createCLI(version: string): Promise<Command> {
 	return program;
 }
 
-async function getRegion(regions: RegionList): Promise<string> {
+async function getRegion(regions: RegionList, preferredRegion?: string): Promise<string> {
 	const firstRegion = regions[0];
 	if (regions.length === 1 && firstRegion) {
 		return firstRegion.region;
 	} else {
+		const preferredIndex = preferredRegion
+			? regions.findIndex((region) => region.region === preferredRegion)
+			: -1;
 		const response = await enquirer.prompt<{ region: string }>({
 			type: 'select',
 			name: 'region',
 			message: 'Select a cloud region:',
+			...(preferredIndex >= 0 && { initial: preferredIndex }),
 			choices: regions.map((r) => ({
 				name: r.region,
 				message: `${r.description.padEnd(15, ' ')} ${tui.muted(r.region)}`,
@@ -687,16 +745,76 @@ async function getRegion(regions: RegionList): Promise<string> {
 	}
 }
 
-interface ResolveRegionOptions {
+const RESOURCE_PREFIXES: Array<{ prefix: string; type: ResourceType }> = [
+	{ prefix: 'sbx_', type: 'sandbox' },
+	{ prefix: 'proj_', type: 'project' },
+	{ prefix: 'db_', type: 'db' },
+	{ prefix: 'deploy_', type: 'deployment' },
+	{ prefix: 'machine_', type: 'machine' },
+	{ prefix: 'que_', type: 'queue' },
+	{ prefix: 'vec_', type: 'vector' },
+	{ prefix: 'kv_', type: 'kv' },
+	{ prefix: 'stream_', type: 'stream' },
+];
+
+type PrefixedResource = { id: string; type: ResourceType };
+
+function getResourceTypeFromId(id: string): ResourceType | undefined {
+	for (const entry of RESOURCE_PREFIXES) {
+		if (id.startsWith(entry.prefix)) {
+			return entry.type;
+		}
+	}
+	return undefined;
+}
+
+function collectPrefixedResources(
+	values?: Record<string, unknown> | unknown[]
+): PrefixedResource[] {
+	if (!values) {
+		return [];
+	}
+	const results = new Map<string, ResourceType>();
+	const addValue = (value: unknown) => {
+		if (typeof value === 'string') {
+			const resourceType = getResourceTypeFromId(value);
+			if (resourceType) {
+				results.set(value, resourceType);
+			}
+			return;
+		}
+		if (Array.isArray(value)) {
+			for (const entry of value) {
+				addValue(entry);
+			}
+		}
+	};
+
+	if (Array.isArray(values)) {
+		for (const entry of values) {
+			addValue(entry);
+		}
+	} else {
+		for (const value of Object.values(values)) {
+			addValue(value);
+		}
+	}
+
+	return Array.from(results.entries()).map(([id, type]) => ({ id, type }));
+}
+
+export interface ResolveRegionOptions {
 	options: Record<string, unknown>;
 	regions: RegionList;
 	logger: Logger;
 	required: boolean;
 	region?: string;
+	config?: Config | null;
+	args?: Record<string, unknown> | unknown[];
 }
 
-async function resolveRegion(opts: ResolveRegionOptions): Promise<string | undefined> {
-	const { options, regions, logger, required } = opts;
+export async function resolveRegion(opts: ResolveRegionOptions): Promise<string | undefined> {
+	const { options, regions, logger, required, config, args } = opts;
 
 	// No regions available
 	if (regions.length === 0) {
@@ -717,7 +835,7 @@ async function resolveRegion(opts: ResolveRegionOptions): Promise<string | undef
 	}
 
 	// Check if region was provided via flag
-	let region = opts.region ?? (options.region as string | undefined);
+	let region = options.region as string | undefined;
 
 	// Validate --region flag if provided
 	if (region) {
@@ -741,6 +859,22 @@ async function resolveRegion(opts: ResolveRegionOptions): Promise<string | undef
 		return region;
 	}
 
+	const profileName = config?.name ?? defaultProfileName;
+	const candidateResources = new Map<string, ResourceType>();
+	for (const resource of collectPrefixedResources(args)) {
+		candidateResources.set(resource.id, resource.type);
+	}
+	for (const resource of collectPrefixedResources(options)) {
+		candidateResources.set(resource.id, resource.type);
+	}
+	for (const [id, type] of candidateResources.entries()) {
+		const cachedInfo = await getResourceInfo(type, profileName, id);
+		if (cachedInfo?.region) {
+			logger.trace('resolved region from cache for %s (%s): %s', id, type, cachedInfo.region);
+			return cachedInfo.region;
+		}
+	}
+
 	// Auto-select if only one region available
 	const singleRegion = regions[0];
 	if (regions.length === 1 && singleRegion) {
@@ -762,6 +896,29 @@ async function resolveRegion(opts: ResolveRegionOptions): Promise<string | undef
 		// If not valid, fall through to error/prompt
 	}
 
+	// Check for preferred region in config
+	const preferredRegion = config?.preferences?.region;
+	if (preferredRegion) {
+		const matchingRegion = regions.find((r) => r.region === preferredRegion);
+		if (matchingRegion) {
+			if (process.stdin.isTTY) {
+				region = await getRegion(regions, matchingRegion.region);
+				return region;
+			}
+			logger.trace('selected preferred region (non-TTY): %s', matchingRegion.region);
+			return matchingRegion.region;
+		}
+	}
+
+	// Check for project region fallback
+	const projectRegion = opts.region;
+	if (projectRegion) {
+		const matchingRegion = regions.find((r) => r.region === projectRegion);
+		if (matchingRegion) {
+			return matchingRegion.region;
+		}
+	}
+
 	// No flag provided - handle TTY vs non-TTY
 	if (required && !process.stdin.isTTY) {
 		const errorFormat = (options as Record<string, unknown>).errorFormat as
@@ -786,6 +943,24 @@ async function resolveRegion(opts: ResolveRegionOptions): Promise<string | undef
 	if (process.stdin.isTTY) {
 		// Interactive mode - prompt user
 		region = await getRegion(regions);
+
+		const hasSavedPreference = !!config?.preferences?.region;
+		const hasEnvRegion = !!process.env.AGENTUITY_REGION;
+		const hasTTY = process.stdin.isTTY && process.stdout.isTTY;
+		if (region && hasTTY && !hasSavedPreference && !hasEnvRegion) {
+			const selectedRegionInfo = regions.find((r) => r.region === region);
+			const regionLabel = selectedRegionInfo
+				? `${selectedRegionInfo.description} (${selectedRegionInfo.region})`
+				: region;
+			const shouldSave = await tui.confirm(
+				`Would you like to set "${regionLabel}" as your default region?`,
+				true
+			);
+			if (shouldSave) {
+				await saveRegion(region);
+			}
+		}
+
 		return region;
 	}
 
@@ -1040,44 +1215,58 @@ async function registerSubcommand(
 		const dirNeeded = normalized.requiresProject || normalized.optionalProject;
 
 		if (dirNeeded) {
-			const projectId = options.projectId as string | undefined;
+			const optionsProjectId = options.projectId as string | undefined;
+
+			// Helper to fetch project from API by ID
+			const fetchProjectFromAPI = async (
+				projectId: string
+			): Promise<ProjectConfig | undefined> => {
+				const auth = await requireAuth(baseCtx);
+				if (auth) {
+					// Create config with auth credentials for API client
+					const configWithAuth = {
+						...baseCtx.config,
+						auth: {
+							api_key: auth.apiKey,
+							user_id: auth.userId,
+							expires: auth.expires.getTime(),
+						},
+					};
+					const apiClient = createAPIClient(baseCtx, configWithAuth as Config);
+					// Check cache first to avoid duplicate API calls
+					const profile = baseCtx.config?.name ?? 'default';
+					let projectDetails = getCachedProject(profile, projectId);
+					if (!projectDetails) {
+						const { projectGet } = await import('@agentuity/server');
+						// Use keys: false to match other callers and ensure cache consistency
+						projectDetails = await projectGet(apiClient, { id: projectId, keys: false });
+						setCachedProject(profile, projectId, projectDetails);
+					}
+					return {
+						projectId: projectDetails.id,
+						orgId: projectDetails.orgId,
+						region: projectDetails.cloudRegion || '',
+					};
+				}
+				return undefined;
+			};
 
-			// If --project-id is provided, fetch project details from API
-			if (projectId) {
+			// Resolution precedence:
+			// 1. --project-id flag (or AGENTUITY_CLOUD_PROJECT_ID env var)
+			// 2. agentuity.json in project directory
+			// 3. config.preferences.projectId (global preference) - fallback only
+			// 4. Interactive selection (if TTY)
+
+			if (optionsProjectId) {
+				// Priority 1: Explicit flag/env var provided
 				try {
-					const auth = await requireAuth(baseCtx);
-					if (auth) {
-						// Create config with auth credentials for API client
-						const configWithAuth = {
-							...baseCtx.config,
-							auth: {
-								api_key: auth.apiKey,
-								user_id: auth.userId,
-								expires: auth.expires.getTime(),
-							},
-						};
-						const apiClient = createAPIClient(baseCtx, configWithAuth as Config);
-						// Check cache first to avoid duplicate API calls
-						const profile = baseCtx.config?.name ?? 'default';
-						let projectDetails = getCachedProject(profile, projectId);
-						if (!projectDetails) {
-							const { projectGet } = await import('@agentuity/server');
-							// Use keys: false to match other callers and ensure cache consistency
-							projectDetails = await projectGet(apiClient, { id: projectId, keys: false });
-							setCachedProject(profile, projectId, projectDetails);
-						}
-						project = {
-							projectId: projectDetails.id,
-							orgId: projectDetails.orgId,
-							region: projectDetails.cloudRegion || '',
-						};
-					}
+					project = await fetchProjectFromAPI(optionsProjectId);
 				} catch (_error) {
 					if (normalized.requiresProject) {
 						exitWithError(
 							createError(
 								ErrorCode.PROJECT_NOT_FOUND,
-								`Project not found: ${projectId}`,
+								`Project not found: ${optionsProjectId}`,
 								undefined,
 								[
 									'Verify the project ID is correct',
@@ -1090,7 +1279,7 @@ async function registerSubcommand(
 					}
 				}
 			} else {
-				// Try to load from directory
+				// Priority 2: Try to load from agentuity.json in directory
 				const dir = (options.dir as string | undefined) ?? process.cwd();
 				projectDir = dir;
 				if (projectDir.startsWith('~/')) {
@@ -1100,14 +1289,35 @@ async function registerSubcommand(
 				try {
 					project = await loadProjectConfig(dir, baseCtx.config);
 				} catch (error) {
-					if (normalized.requiresProject) {
-						if (
-							error &&
-							typeof error === 'object' &&
-							'name' in error &&
-							error.name === 'ProjectConfigNotFoundException'
-						) {
-							// If TTY is available, prompt user to select a project
+					const isConfigNotFound =
+						error &&
+						typeof error === 'object' &&
+						'name' in error &&
+						error.name === 'ProjectConfigNotFoundException';
+
+					if (isConfigNotFound) {
+						// Priority 3: Try global preference (only when no agentuity.json found)
+						const projectIdFromPreference = baseCtx.config?.preferences?.projectId as
+							| string
+							| undefined;
+						if (projectIdFromPreference) {
+							try {
+								project = await fetchProjectFromAPI(projectIdFromPreference);
+								if (project) {
+									// Set the project ID in options so it can be used by the command
+									(options as Record<string, unknown>).projectId = projectIdFromPreference;
+								}
+							} catch (_preferenceError) {
+								// Preference project not found, fall through to interactive selection
+								baseCtx.logger.trace(
+									'Preference project not found: %s',
+									projectIdFromPreference
+								);
+							}
+						}
+
+						// Priority 4: Interactive selection (if TTY and still no project)
+						if (!project && normalized.requiresProject) {
 							const hasTTY = process.stdin.isTTY && process.stdout.isTTY;
 
 							if (hasTTY) {
@@ -1143,9 +1353,9 @@ async function registerSubcommand(
 									baseCtx.options.errorFormat
 								);
 							}
-						} else {
-							throw error;
 						}
+					} else if (normalized.requiresProject) {
+						throw error;
 					}
 					// For optional projects, silently continue without project config
 				}
@@ -1200,11 +1410,25 @@ async function registerSubcommand(
 					}
 					// Auto-select org when --confirm flag is used
 					const autoSelectOrg = options.confirm === true;
+					const hasPrefixedId = hasPrefixedResourceId(
+						ctx.args as Record<string, unknown> | undefined,
+						ctx.opts as Record<string, unknown> | undefined
+					);
+					const prefixedOrgId = hasPrefixedId
+						? await resolveOrgIdWithoutPrompt({
+								options,
+								config: (ctx.config as Config | null) ?? null,
+								args: ctx.args as Record<string, unknown> | undefined,
+								opts: ctx.opts as Record<string, unknown> | undefined,
+							})
+						: undefined;
 					if (normalized.requiresOrg) {
-						ctx.orgId = await requireOrg(
-							ctx as CommandContext & { apiClient: APIClientType },
-							autoSelectOrg
-						);
+						ctx.orgId = hasPrefixedId
+							? prefixedOrgId
+							: await requireOrg(
+									ctx as CommandContext & { apiClient: APIClientType },
+									autoSelectOrg
+								);
 					}
 					// Skip org handling if --no-register is set (org only needed for registration)
 					const skipOrg =
@@ -1214,10 +1438,12 @@ async function registerSubcommand(
 						(ctx.opts as Record<string, unknown>).register === false;
 
 					if (normalized.optionalOrg && ctx.auth && !skipOrg) {
-						ctx.orgId = await selectOptionalOrg(
-							ctx as CommandContext & { apiClient: APIClientType },
-							autoSelectOrg
-						);
+						ctx.orgId = hasPrefixedId
+							? prefixedOrgId
+							: await selectOptionalOrg(
+									ctx as CommandContext & { apiClient: APIClientType },
+									autoSelectOrg
+								);
 					}
 					// Skip region handling if --no-register is set (region only needed for registration)
 					const skipRegion =
@@ -1252,10 +1478,12 @@ async function registerSubcommand(
 						if (normalized.requiresRegion || normalized.optionalRegion) {
 							const region = await resolveRegion({
 								options: options as Record<string, unknown>,
+								args: ctx.args as Record<string, unknown> | undefined,
 								regions,
 								logger: baseCtx.logger,
 								required: !!normalized.requiresRegion,
 								region: project?.region,
+								config: baseCtx.config ?? null,
 							});
 							if (region) {
 								ctx.region = region;
@@ -1308,11 +1536,21 @@ async function registerSubcommand(
 				}
 				// Auto-select org when --confirm flag is used
 				const autoSelectOrg2 = options.confirm === true;
+				const hasPrefixedId = hasPrefixedResourceId(args as unknown[]);
+				const prefixedOrgId = hasPrefixedId
+					? await resolveOrgIdWithoutPrompt({
+							options,
+							config: (ctx.config as Config | null) ?? null,
+							args: args as unknown[],
+						})
+					: undefined;
 				if (normalized.requiresOrg) {
-					ctx.orgId = await requireOrg(
-						ctx as CommandContext & { apiClient: APIClientType },
-						autoSelectOrg2
-					);
+					ctx.orgId = hasPrefixedId
+						? prefixedOrgId
+						: await requireOrg(
+								ctx as CommandContext & { apiClient: APIClientType },
+								autoSelectOrg2
+							);
 				}
 				// Skip org handling if --no-register is set (org only needed for registration)
 				const skipOrg =
@@ -1322,10 +1560,12 @@ async function registerSubcommand(
 					(ctx.opts as Record<string, unknown>).register === false;
 
 				if (normalized.optionalOrg && ctx.auth && !skipOrg) {
-					ctx.orgId = await selectOptionalOrg(
-						ctx as CommandContext & { apiClient: APIClientType },
-						autoSelectOrg2
-					);
+					ctx.orgId = hasPrefixedId
+						? prefixedOrgId
+						: await selectOptionalOrg(
+								ctx as CommandContext & { apiClient: APIClientType },
+								autoSelectOrg2
+							);
 				}
 				// Skip region handling if --no-register is set (region only needed for registration)
 				const skipRegion =
@@ -1360,10 +1600,12 @@ async function registerSubcommand(
 					if (normalized.requiresRegion || normalized.optionalRegion) {
 						const region = await resolveRegion({
 							options: options as Record<string, unknown>,
+							args: args as unknown[],
 							regions,
 							logger: baseCtx.logger,
 							required: !!normalized.requiresRegion,
 							region: project?.region,
+							config: baseCtx.config ?? null,
 						});
 						if (region) {
 							ctx.region = region;
@@ -1371,8 +1613,9 @@ async function registerSubcommand(
 					}
 				}
 				if (subcommand.handler) {
-					maybeRenderWebLink(ctx as CommandContext, subcommand.webUrl);
 					const result = await subcommand.handler(ctx as CommandContext);
+					// Render "View on the web" link after successful execution (not shown on errors)
+					maybeRenderWebLink(ctx as CommandContext, subcommand.webUrl);
 
 					// If --json flag is set
 					if (baseCtx.options.json) {
@@ -1466,11 +1709,25 @@ async function registerSubcommand(
 					);
 					// Auto-select org when --confirm flag is used
 					const autoSelectOrg3 = options.confirm === true;
+					const hasPrefixedId3 = hasPrefixedResourceId(
+						ctx.args as Record<string, unknown> | undefined,
+						ctx.opts as Record<string, unknown> | undefined
+					);
+					const prefixedOrgId3 = hasPrefixedId3
+						? await resolveOrgIdWithoutPrompt({
+								options,
+								config: (ctx.config as Config | null) ?? null,
+								args: ctx.args as Record<string, unknown> | undefined,
+								opts: ctx.opts as Record<string, unknown> | undefined,
+							})
+						: undefined;
 					if (normalized.requiresOrg && ctx.apiClient) {
-						ctx.orgId = await requireOrg(
-							ctx as CommandContext & { apiClient: APIClientType },
-							autoSelectOrg3
-						);
+						ctx.orgId = hasPrefixedId3
+							? prefixedOrgId3
+							: await requireOrg(
+									ctx as CommandContext & { apiClient: APIClientType },
+									autoSelectOrg3
+								);
 					}
 					// Skip org handling if --no-register is set (org only needed for registration)
 					const skipOrg =
@@ -1480,10 +1737,12 @@ async function registerSubcommand(
 						(ctx.opts as Record<string, unknown>).register === false;
 
 					if (normalized.optionalOrg && ctx.apiClient && auth && !skipOrg) {
-						ctx.orgId = await selectOptionalOrg(
-							ctx as CommandContext & { apiClient?: APIClientType; auth?: AuthData },
-							autoSelectOrg3
-						);
+						ctx.orgId = hasPrefixedId3
+							? prefixedOrgId3
+							: await selectOptionalOrg(
+									ctx as CommandContext & { apiClient?: APIClientType; auth?: AuthData },
+									autoSelectOrg3
+								);
 						baseCtx.logger.trace('selected orgId: %s', ctx.orgId);
 					}
 					// Skip region handling if --no-register is set (region only needed for registration)
@@ -1513,10 +1772,12 @@ async function registerSubcommand(
 						});
 						const region = await resolveRegion({
 							options: options as Record<string, unknown>,
+							args: ctx.args as Record<string, unknown> | undefined,
 							regions,
 							logger: baseCtx.logger,
 							required: !!normalized.requiresRegion,
 							region: project?.region,
+							config: baseCtx.config ?? null,
 						});
 						if (region) {
 							ctx.region = region;
@@ -1567,11 +1828,21 @@ async function registerSubcommand(
 				}
 				// Auto-select org when --confirm flag is used
 				const autoSelectOrg4 = options.confirm === true;
+				const hasPrefixedId4 = hasPrefixedResourceId(args as unknown[]);
+				const prefixedOrgId4 = hasPrefixedId4
+					? await resolveOrgIdWithoutPrompt({
+							options,
+							config: (ctx.config as Config | null) ?? null,
+							args: args as unknown[],
+						})
+					: undefined;
 				if (normalized.requiresOrg && ctx.apiClient) {
-					ctx.orgId = await requireOrg(
-						ctx as CommandContext & { apiClient: APIClientType },
-						autoSelectOrg4
-					);
+					ctx.orgId = hasPrefixedId4
+						? prefixedOrgId4
+						: await requireOrg(
+								ctx as CommandContext & { apiClient: APIClientType },
+								autoSelectOrg4
+							);
 				}
 				// Skip org handling if --no-register is set (org only needed for registration)
 				// For non-schema commands, check options directly (Commander passes all options)
@@ -1581,10 +1852,12 @@ async function registerSubcommand(
 					(options as Record<string, unknown>).register === false;
 
 				if (normalized.optionalOrg && ctx.apiClient && !skipOrg) {
-					ctx.orgId = await selectOptionalOrg(
-						ctx as CommandContext & { apiClient?: APIClientType; auth?: AuthData },
-						autoSelectOrg4
-					);
+					ctx.orgId = hasPrefixedId4
+						? prefixedOrgId4
+						: await selectOptionalOrg(
+								ctx as CommandContext & { apiClient?: APIClientType; auth?: AuthData },
+								autoSelectOrg4
+							);
 				}
 				// Skip region handling if --no-register is set (region only needed for registration)
 				const skipRegion =
@@ -1611,18 +1884,21 @@ async function registerSubcommand(
 					});
 					const region = await resolveRegion({
 						options: options as Record<string, unknown>,
+						args: args as unknown[],
 						regions,
 						logger: baseCtx.logger,
 						required: !!normalized.requiresRegion,
 						region: project?.region,
+						config: baseCtx.config ?? null,
 					});
 					if (region) {
 						ctx.region = region;
 					}
 				}
 				if (subcommand.handler) {
-					maybeRenderWebLink(ctx as CommandContext, subcommand.webUrl);
 					const result = await subcommand.handler(ctx as CommandContext);
+					// Render "View on the web" link after successful execution (not shown on errors)
+					maybeRenderWebLink(ctx as CommandContext, subcommand.webUrl);
 
 					// If --json flag is set
 					if (baseCtx.options.json) {
@@ -1750,18 +2026,21 @@ async function registerSubcommand(
 					});
 					const region = await resolveRegion({
 						options: options as Record<string, unknown>,
+						args: args as unknown[],
 						regions,
 						logger: baseCtx.logger,
 						required: !!normalized.requiresRegion,
 						region: project?.region,
+						config: baseCtx.config ?? null,
 					});
 					if (region) {
 						ctx.region = region;
 					}
 				}
 				if (subcommand.handler) {
-					maybeRenderWebLink(ctx as CommandContext, subcommand.webUrl);
 					const result = await subcommand.handler(ctx as CommandContext);
+					// Render "View on the web" link after successful execution (not shown on errors)
+					maybeRenderWebLink(ctx as CommandContext, subcommand.webUrl);
 
 					// If --json flag is set
 					if (baseCtx.options.json) {
@@ -1892,6 +2171,7 @@ export async function registerCommands(
 								regions,
 								logger: baseCtx.logger,
 								required: !!normalized.requiresRegion,
+								config: baseCtx.config ?? null,
 							});
 							if (region) {
 								ctx.region = region;
@@ -1960,6 +2240,7 @@ export async function registerCommands(
 								regions,
 								logger: baseCtx.logger,
 								required: !!normalized.requiresRegion,
+								config: baseCtx.config ?? null,
 							});
 							if (region) {
 								ctx.region = region;
@@ -1991,6 +2272,7 @@ export async function registerCommands(
 								regions,
 								logger: baseCtx.logger,
 								required: !!normalized.requiresRegion,
+								config: baseCtx.config ?? null,
 							});
 							if (region) {
 								ctx.region = region;