@agentuity/cli 1.0.0 → 1.0.2

package/dist/cli.js

@@ -2,20 +2,22 @@ import { homedir } from 'node:os';
 import { resolve } from 'node:path';
 import { Command } from 'commander';
 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 { 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 } from './api';
 import { ErrorCode, ExitCode, createError, exitWithError } from './errors';
 import { getCommand } from './command-prefix';
 import { isValidateMode, outputValidation } 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, hasAgentSeenIntro, markAgentIntroSeen, } from './cache';
 /**
  * Check if an error is a CLI input validation error (Zod error from schema parsing),
  * and not an API response validation error (ValidationOutputError).
@@ -98,10 +100,10 @@ async function executeOrValidate(ctx, commandName, handler, hasResponseSchema, w
         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
@@ -352,6 +354,9 @@ async function promptProjectSelection(baseCtx) {
     if (!selectedProject) {
         return null;
     }
+    if (selectedProject.id !== config?.preferences?.projectId) {
+        await saveProjectId(selectedProject.id);
+    }
     // Convert to ProjectConfig format
     return {
         projectId: selectedProject.id,
@@ -375,6 +380,7 @@ export async function createCLI(version) {
         .option('--log-timestamp', 'Show timestamps in log output', false)
         .option('--no-log-prefix', 'Hide log level prefixes', true)
         .option('--org-id <id>', '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')
@@ -383,10 +389,14 @@ export async function createCLI(version) {
         .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', 'Skip version compatibility check (dev only)');
     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();
     });
@@ -485,14 +495,32 @@ export async function createCLI(version) {
             }
             // 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.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
             const description = helper.commandDescription(cmd);
@@ -537,16 +565,20 @@ export async function createCLI(version) {
     });
     return program;
 }
-async function getRegion(regions) {
+async function getRegion(regions, preferredRegion) {
     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({
             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)}`,
@@ -555,8 +587,58 @@ async function getRegion(regions) {
         return response.region;
     }
 }
-async function resolveRegion(opts) {
-    const { options, regions, logger, required } = opts;
+const RESOURCE_PREFIXES = [
+    { 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' },
+];
+function getResourceTypeFromId(id) {
+    for (const entry of RESOURCE_PREFIXES) {
+        if (id.startsWith(entry.prefix)) {
+            return entry.type;
+        }
+    }
+    return undefined;
+}
+function collectPrefixedResources(values) {
+    if (!values) {
+        return [];
+    }
+    const results = new Map();
+    const addValue = (value) => {
+        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 async function resolveRegion(opts) {
+    const { options, regions, logger, required, config, args } = opts;
     // No regions available
     if (regions.length === 0) {
         if (required) {
@@ -568,7 +650,7 @@ async function resolveRegion(opts) {
         return undefined;
     }
     // Check if region was provided via flag
-    let region = opts.region ?? options.region;
+    let region = options.region;
     // Validate --region flag if provided
     if (region) {
         const found = regions.find((r) => r.region === region);
@@ -578,6 +660,21 @@ async function resolveRegion(opts) {
         }
         return region;
     }
+    const profileName = config?.name ?? defaultProfileName;
+    const candidateResources = new Map();
+    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) {
@@ -597,6 +694,27 @@ async function resolveRegion(opts) {
         }
         // 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.errorFormat;
@@ -608,6 +726,19 @@ async function resolveRegion(opts) {
     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;
     }
     // Non-interactive, optional region - return undefined
@@ -824,41 +955,51 @@ async function registerSubcommand(parent, subcommand, baseCtx, hidden) {
         let projectDir;
         const dirNeeded = normalized.requiresProject || normalized.optionalProject;
         if (dirNeeded) {
-            const projectId = options.projectId;
-            // If --project-id is provided, fetch project details from API
-            if (projectId) {
-                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);
-                        // 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 || '',
-                        };
+            const optionsProjectId = options.projectId;
+            // Helper to fetch project from API by ID
+            const fetchProjectFromAPI = async (projectId) => {
+                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);
+                    // 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;
+            };
+            // 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 {
+                    project = await fetchProjectFromAPI(optionsProjectId);
                 }
                 catch (_error) {
                     if (normalized.requiresProject) {
-                        exitWithError(createError(ErrorCode.PROJECT_NOT_FOUND, `Project not found: ${projectId}`, undefined, [
+                        exitWithError(createError(ErrorCode.PROJECT_NOT_FOUND, `Project not found: ${optionsProjectId}`, undefined, [
                             'Verify the project ID is correct',
                             `Run "${getCommand('project list')}" to see available projects`,
                         ]), baseCtx.logger, baseCtx.options.errorFormat);
@@ -866,7 +1007,7 @@ async function registerSubcommand(parent, subcommand, baseCtx, hidden) {
                 }
             }
             else {
-                // Try to load from directory
+                // Priority 2: Try to load from agentuity.json in directory
                 const dir = options.dir ?? process.cwd();
                 projectDir = dir;
                 if (projectDir.startsWith('~/')) {
@@ -877,12 +1018,28 @@ async function registerSubcommand(parent, subcommand, baseCtx, hidden) {
                     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;
+                        if (projectIdFromPreference) {
+                            try {
+                                project = await fetchProjectFromAPI(projectIdFromPreference);
+                                if (project) {
+                                    // Set the project ID in options so it can be used by the command
+                                    options.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) {
                                 // Try to prompt for project selection
@@ -909,9 +1066,9 @@ async function registerSubcommand(parent, subcommand, baseCtx, hidden) {
                                 ]), baseCtx.logger, baseCtx.options.errorFormat);
                             }
                         }
-                        else {
-                            throw error;
-                        }
+                    }
+                    else if (normalized.requiresProject) {
+                        throw error;
                     }
                     // For optional projects, silently continue without project config
                 }
@@ -960,8 +1117,19 @@ async function registerSubcommand(parent, subcommand, baseCtx, hidden) {
                     }
                     // Auto-select org when --confirm flag is used
                     const autoSelectOrg = options.confirm === true;
+                    const hasPrefixedId = hasPrefixedResourceId(ctx.args, ctx.opts);
+                    const prefixedOrgId = hasPrefixedId
+                        ? await resolveOrgIdWithoutPrompt({
+                            options,
+                            config: ctx.config ?? null,
+                            args: ctx.args,
+                            opts: ctx.opts,
+                        })
+                        : undefined;
                     if (normalized.requiresOrg) {
-                        ctx.orgId = await requireOrg(ctx, autoSelectOrg);
+                        ctx.orgId = hasPrefixedId
+                            ? prefixedOrgId
+                            : await requireOrg(ctx, autoSelectOrg);
                     }
                     // Skip org handling if --no-register is set (org only needed for registration)
                     const skipOrg = normalized.optionalOrg &&
@@ -969,7 +1137,9 @@ async function registerSubcommand(parent, subcommand, baseCtx, hidden) {
                         ctx.opts &&
                         ctx.opts.register === false;
                     if (normalized.optionalOrg && ctx.auth && !skipOrg) {
-                        ctx.orgId = await selectOptionalOrg(ctx, autoSelectOrg);
+                        ctx.orgId = hasPrefixedId
+                            ? prefixedOrgId
+                            : await selectOptionalOrg(ctx, autoSelectOrg);
                     }
                     // Skip region handling if --no-register is set (region only needed for registration)
                     const skipRegion = normalized.optionalRegion &&
@@ -996,10 +1166,12 @@ async function registerSubcommand(parent, subcommand, baseCtx, hidden) {
                         if (normalized.requiresRegion || normalized.optionalRegion) {
                             const region = await resolveRegion({
                                 options: options,
+                                args: ctx.args,
                                 regions,
                                 logger: baseCtx.logger,
                                 required: !!normalized.requiresRegion,
                                 region: project?.region,
+                                config: baseCtx.config ?? null,
                             });
                             if (region) {
                                 ctx.region = region;
@@ -1043,8 +1215,18 @@ async function registerSubcommand(parent, subcommand, baseCtx, hidden) {
                 }
                 // Auto-select org when --confirm flag is used
                 const autoSelectOrg2 = options.confirm === true;
+                const hasPrefixedId = hasPrefixedResourceId(args);
+                const prefixedOrgId = hasPrefixedId
+                    ? await resolveOrgIdWithoutPrompt({
+                        options,
+                        config: ctx.config ?? null,
+                        args: args,
+                    })
+                    : undefined;
                 if (normalized.requiresOrg) {
-                    ctx.orgId = await requireOrg(ctx, autoSelectOrg2);
+                    ctx.orgId = hasPrefixedId
+                        ? prefixedOrgId
+                        : await requireOrg(ctx, autoSelectOrg2);
                 }
                 // Skip org handling if --no-register is set (org only needed for registration)
                 const skipOrg = normalized.optionalOrg &&
@@ -1052,7 +1234,9 @@ async function registerSubcommand(parent, subcommand, baseCtx, hidden) {
                     ctx.opts &&
                     ctx.opts.register === false;
                 if (normalized.optionalOrg && ctx.auth && !skipOrg) {
-                    ctx.orgId = await selectOptionalOrg(ctx, autoSelectOrg2);
+                    ctx.orgId = hasPrefixedId
+                        ? prefixedOrgId
+                        : await selectOptionalOrg(ctx, autoSelectOrg2);
                 }
                 // Skip region handling if --no-register is set (region only needed for registration)
                 const skipRegion = normalized.optionalRegion &&
@@ -1079,10 +1263,12 @@ async function registerSubcommand(parent, subcommand, baseCtx, hidden) {
                     if (normalized.requiresRegion || normalized.optionalRegion) {
                         const region = await resolveRegion({
                             options: options,
+                            args: args,
                             regions,
                             logger: baseCtx.logger,
                             required: !!normalized.requiresRegion,
                             region: project?.region,
+                            config: baseCtx.config ?? null,
                         });
                         if (region) {
                             ctx.region = region;
@@ -1090,8 +1276,9 @@ async function registerSubcommand(parent, subcommand, baseCtx, hidden) {
                     }
                 }
                 if (subcommand.handler) {
-                    maybeRenderWebLink(ctx, subcommand.webUrl);
                     const result = await subcommand.handler(ctx);
+                    // Render "View on the web" link after successful execution (not shown on errors)
+                    maybeRenderWebLink(ctx, subcommand.webUrl);
                     // If --json flag is set
                     if (baseCtx.options.json) {
                         // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -1159,8 +1346,19 @@ async function registerSubcommand(parent, subcommand, baseCtx, hidden) {
                     baseCtx.logger.trace('optionalAuth path: org=%s, region=%s, hasApiClient=%s, hasAuth=%s', normalized.optionalOrg, normalized.optionalRegion, !!ctx.apiClient, !!auth);
                     // Auto-select org when --confirm flag is used
                     const autoSelectOrg3 = options.confirm === true;
+                    const hasPrefixedId3 = hasPrefixedResourceId(ctx.args, ctx.opts);
+                    const prefixedOrgId3 = hasPrefixedId3
+                        ? await resolveOrgIdWithoutPrompt({
+                            options,
+                            config: ctx.config ?? null,
+                            args: ctx.args,
+                            opts: ctx.opts,
+                        })
+                        : undefined;
                     if (normalized.requiresOrg && ctx.apiClient) {
-                        ctx.orgId = await requireOrg(ctx, autoSelectOrg3);
+                        ctx.orgId = hasPrefixedId3
+                            ? prefixedOrgId3
+                            : await requireOrg(ctx, autoSelectOrg3);
                     }
                     // Skip org handling if --no-register is set (org only needed for registration)
                     const skipOrg = normalized.optionalOrg &&
@@ -1168,7 +1366,9 @@ async function registerSubcommand(parent, subcommand, baseCtx, hidden) {
                         ctx.opts &&
                         ctx.opts.register === false;
                     if (normalized.optionalOrg && ctx.apiClient && auth && !skipOrg) {
-                        ctx.orgId = await selectOptionalOrg(ctx, autoSelectOrg3);
+                        ctx.orgId = hasPrefixedId3
+                            ? prefixedOrgId3
+                            : await selectOptionalOrg(ctx, autoSelectOrg3);
                         baseCtx.logger.trace('selected orgId: %s', ctx.orgId);
                     }
                     // Skip region handling if --no-register is set (region only needed for registration)
@@ -1190,10 +1390,12 @@ async function registerSubcommand(parent, subcommand, baseCtx, hidden) {
                         });
                         const region = await resolveRegion({
                             options: options,
+                            args: ctx.args,
                             regions,
                             logger: baseCtx.logger,
                             required: !!normalized.requiresRegion,
                             region: project?.region,
+                            config: baseCtx.config ?? null,
                         });
                         if (region) {
                             ctx.region = region;
@@ -1235,8 +1437,18 @@ async function registerSubcommand(parent, subcommand, baseCtx, hidden) {
                 }
                 // Auto-select org when --confirm flag is used
                 const autoSelectOrg4 = options.confirm === true;
+                const hasPrefixedId4 = hasPrefixedResourceId(args);
+                const prefixedOrgId4 = hasPrefixedId4
+                    ? await resolveOrgIdWithoutPrompt({
+                        options,
+                        config: ctx.config ?? null,
+                        args: args,
+                    })
+                    : undefined;
                 if (normalized.requiresOrg && ctx.apiClient) {
-                    ctx.orgId = await requireOrg(ctx, autoSelectOrg4);
+                    ctx.orgId = hasPrefixedId4
+                        ? prefixedOrgId4
+                        : await requireOrg(ctx, 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)
@@ -1244,7 +1456,9 @@ async function registerSubcommand(parent, subcommand, baseCtx, hidden) {
                     !normalized.requiresOrg &&
                     options.register === false;
                 if (normalized.optionalOrg && ctx.apiClient && !skipOrg) {
-                    ctx.orgId = await selectOptionalOrg(ctx, autoSelectOrg4);
+                    ctx.orgId = hasPrefixedId4
+                        ? prefixedOrgId4
+                        : await selectOptionalOrg(ctx, autoSelectOrg4);
                 }
                 // Skip region handling if --no-register is set (region only needed for registration)
                 const skipRegion = normalized.optionalRegion &&
@@ -1263,18 +1477,21 @@ async function registerSubcommand(parent, subcommand, baseCtx, hidden) {
                     });
                     const region = await resolveRegion({
                         options: options,
+                        args: args,
                         regions,
                         logger: baseCtx.logger,
                         required: !!normalized.requiresRegion,
                         region: project?.region,
+                        config: baseCtx.config ?? null,
                     });
                     if (region) {
                         ctx.region = region;
                     }
                 }
                 if (subcommand.handler) {
-                    maybeRenderWebLink(ctx, subcommand.webUrl);
                     const result = await subcommand.handler(ctx);
+                    // Render "View on the web" link after successful execution (not shown on errors)
+                    maybeRenderWebLink(ctx, subcommand.webUrl);
                     // If --json flag is set
                     if (baseCtx.options.json) {
                         // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -1368,18 +1585,21 @@ async function registerSubcommand(parent, subcommand, baseCtx, hidden) {
                     });
                     const region = await resolveRegion({
                         options: options,
+                        args: args,
                         regions,
                         logger: baseCtx.logger,
                         required: !!normalized.requiresRegion,
                         region: project?.region,
+                        config: baseCtx.config ?? null,
                     });
                     if (region) {
                         ctx.region = region;
                     }
                 }
                 if (subcommand.handler) {
-                    maybeRenderWebLink(ctx, subcommand.webUrl);
                     const result = await subcommand.handler(ctx);
+                    // Render "View on the web" link after successful execution (not shown on errors)
+                    maybeRenderWebLink(ctx, subcommand.webUrl);
                     // If --json flag is set
                     if (baseCtx.options.json) {
                         // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -1478,6 +1698,7 @@ export async function registerCommands(program, commands, baseCtx) {
                                 regions,
                                 logger: baseCtx.logger,
                                 required: !!normalized.requiresRegion,
+                                config: baseCtx.config ?? null,
                             });
                             if (region) {
                                 ctx.region = region;
@@ -1534,6 +1755,7 @@ export async function registerCommands(program, commands, baseCtx) {
                                 regions,
                                 logger: baseCtx.logger,
                                 required: !!normalized.requiresRegion,
+                                config: baseCtx.config ?? null,
                             });
                             if (region) {
                                 ctx.region = region;
@@ -1562,6 +1784,7 @@ export async function registerCommands(program, commands, baseCtx) {
                                 regions,
                                 logger: baseCtx.logger,
                                 required: !!normalized.requiresRegion,
+                                config: baseCtx.config ?? null,
                             });
                             if (region) {
                                 ctx.region = region;