@agentuity/cli 0.1.8 → 0.1.10

package/src/cmd/cloud/sandbox/snapshot/get.ts

@@ -1,11 +1,11 @@
 import { z } from 'zod';
 import { createCommand } from '../../../../types';
 import * as tui from '../../../../tui';
-import { createSandboxClient } from '../util';
 import { getCommand } from '../../../../command-prefix';
 import { snapshotGet, sandboxList } from '@agentuity/server';
 import type { SnapshotFileInfo } from '@agentuity/server';
 import type { SandboxInfo } from '@agentuity/core';
+import { getGlobalCatalystAPIClient } from '../../../../config';
 
 const SnapshotFileSchema = z.object({
 	path: z.string(),
@@ -27,7 +27,7 @@ const SnapshotGetResponseSchema = z.object({
 	parentSnapshotId: z.string().nullable().optional().describe('Parent snapshot ID'),
 	createdAt: z.string().describe('Creation timestamp'),
 	downloadUrl: z.string().optional().describe('Presigned download URL'),
-	files: z.array(SnapshotFileSchema).optional().describe('Files in snapshot'),
+	files: z.array(SnapshotFileSchema).nullable().optional().describe('Files in snapshot'),
 	sandboxes: z
 		.array(SandboxInfoSchema)
 		.optional()
@@ -39,7 +39,7 @@ export const getSubcommand = createCommand({
 	aliases: ['info', 'show'],
 	description: 'Get snapshot details',
 	tags: ['slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	examples: [
 		{
 			command: getCommand('cloud sandbox snapshot get snp_abc123'),
@@ -54,8 +54,8 @@ export const getSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args, options, auth, region, logger, orgId } = ctx;
-		const client = createSandboxClient(logger, auth, region);
+		const { args, options, auth, logger, orgId, config } = ctx;
+		const client = await getGlobalCatalystAPIClient(logger, auth, config?.name);
 
 		const snapshot = await snapshotGet(client, {
 			snapshotId: args.snapshotId,

package/src/cmd/cloud/sandbox/snapshot/index.ts

@@ -22,7 +22,7 @@ export const snapshotCommand = createCommand({
 		},
 	],
 	subcommands: [createSubcommand, listSubcommand, getSubcommand, deleteSubcommand, tagSubcommand],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 });
 
 export default snapshotCommand;

package/src/cmd/cloud/sandbox/snapshot/list.ts

@@ -1,12 +1,14 @@
 import { z } from 'zod';
 import { createCommand } from '../../../../types';
 import * as tui from '../../../../tui';
-import { createSandboxClient } from '../util';
 import { getCommand } from '../../../../command-prefix';
 import { snapshotList } from '@agentuity/server';
+import { getGlobalCatalystAPIClient } from '../../../../config';
 
 const SnapshotInfoSchema = z.object({
 	snapshotId: z.string(),
+	name: z.string().nullable().optional(),
+	description: z.string().nullable().optional(),
 	tag: z.string().nullable().optional(),
 	sizeBytes: z.number(),
 	fileCount: z.number(),
@@ -24,7 +26,7 @@ export const listSubcommand = createCommand({
 	aliases: ['ls'],
 	description: 'List snapshots',
 	tags: ['slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	examples: [
 		{
 			command: getCommand('cloud sandbox snapshot list'),
@@ -45,8 +47,8 @@ export const listSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { opts, options, auth, region, logger, orgId } = ctx;
-		const client = createSandboxClient(logger, auth, region);
+		const { opts, options, auth, logger, orgId, config } = ctx;
+		const client = await getGlobalCatalystAPIClient(logger, auth, config?.name);
 
 		const result = await snapshotList(client, {
 			sandboxId: opts.sandbox,
@@ -62,6 +64,7 @@ export const listSubcommand = createCommand({
 				const tableData = result.snapshots.map((snap) => {
 					return {
 						ID: snap.snapshotId,
+						Name: snap.name ?? '-',
 						Tag: snap.tag ?? '-',
 						Size: tui.formatBytes(snap.sizeBytes),
 						Files: snap.fileCount,
@@ -70,6 +73,7 @@ export const listSubcommand = createCommand({
 				});
 				tui.table(tableData, [
 					{ name: 'ID', alignment: 'left' },
+					{ name: 'Name', alignment: 'left' },
 					{ name: 'Tag', alignment: 'left' },
 					{ name: 'Size', alignment: 'right' },
 					{ name: 'Files', alignment: 'right' },

package/src/cmd/cloud/sandbox/snapshot/tag.ts

@@ -1,9 +1,12 @@
 import { z } from 'zod';
 import { createCommand } from '../../../../types';
 import * as tui from '../../../../tui';
-import { createSandboxClient } from '../util';
 import { getCommand } from '../../../../command-prefix';
 import { snapshotTag } from '@agentuity/server';
+import { getGlobalCatalystAPIClient } from '../../../../config';
+
+const SNAPSHOT_TAG_REGEX = /^[a-zA-Z0-9_][a-zA-Z0-9._-]*$/;
+const MAX_SNAPSHOT_TAG_LENGTH = 128;
 
 const SnapshotTagResponseSchema = z.object({
 	snapshotId: z.string().describe('Snapshot ID'),
@@ -14,7 +17,7 @@ export const tagSubcommand = createCommand({
 	name: 'tag',
 	description: 'Add or update a tag on a snapshot',
 	tags: ['slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	examples: [
 		{
 			command: getCommand('cloud sandbox snapshot tag snp_abc123 latest'),
@@ -37,13 +40,26 @@ export const tagSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args, opts, options, auth, region, logger, orgId } = ctx;
-		const client = createSandboxClient(logger, auth, region);
+		const { args, opts, options, auth, logger, orgId, config } = ctx;
+		const client = await getGlobalCatalystAPIClient(logger, auth, config?.name);
 
 		if (!args.tag && !opts.clear) {
 			throw new Error('Either provide a tag name or use --clear to remove the tag');
 		}
 
+		if (args.tag) {
+			if (args.tag.length > MAX_SNAPSHOT_TAG_LENGTH) {
+				logger.fatal(
+					`Invalid snapshot tag: must be at most ${MAX_SNAPSHOT_TAG_LENGTH} characters`
+				);
+			}
+			if (!SNAPSHOT_TAG_REGEX.test(args.tag)) {
+				logger.fatal(
+					'Invalid snapshot tag: must only contain letters, numbers, dashes, underscores, and dots, and cannot start with a period or dash'
+				);
+			}
+		}
+
 		const tag = opts.clear ? null : (args.tag ?? null);
 
 		const snapshot = await snapshotTag(client, {

package/src/cmd/cloud/sandbox/upload.ts

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { readFileSync, statSync } from 'node:fs';
 import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
-import { createSandboxClient } from './util';
+import { createSandboxClient, getSandboxRegion } from './util';
 import { getCommand } from '../../../command-prefix';
 import { sandboxUploadArchive } from '@agentuity/server';
 
@@ -11,7 +11,7 @@ export const uploadSubcommand = createCommand({
 	aliases: ['ul'],
 	description: 'Upload a compressed archive to a sandbox and extract it',
 	tags: ['slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	examples: [
 		{
 			command: getCommand('cloud sandbox upload sbx_abc123 ./archive.tar.gz'),
@@ -45,8 +45,9 @@ export const uploadSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args, opts, options, auth, region, logger, orgId } = ctx;
+		const { args, opts, options, auth, logger, orgId, config } = ctx;
 
+		const region = await getSandboxRegion(logger, auth, config?.name, args.sandboxId, orgId);
 		const client = createSandboxClient(logger, auth, region);
 
 		const stat = statSync(args.archive);

package/src/cmd/cloud/sandbox/util.ts

@@ -1,14 +1,73 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import type { Logger, FileToWrite } from '@agentuity/core';
-import { APIClient, getServiceUrls } from '@agentuity/server';
+import { APIClient, getServiceUrls, sandboxGet } from '@agentuity/server';
 import type { AuthData } from '../../../types';
+import { getGlobalCatalystAPIClient } from '../../../config';
+import { getResourceRegion, setResourceRegion, deleteResourceRegion } from '../../../cache';
+import * as tui from '../../../tui';
+import { ErrorCode } from '../../../errors';
 
 export function createSandboxClient(logger: Logger, auth: AuthData, region: string): APIClient {
 	const urls = getServiceUrls(region);
 	return new APIClient(urls.catalyst, logger, auth.apiKey);
 }
 
+/**
+ * Look up the region for a sandbox, using cache-first strategy.
+ * Falls back to API lookup if not in cache.
+ */
+export async function getSandboxRegion(
+	logger: Logger,
+	auth: AuthData,
+	profileName = 'production',
+	sandboxId: string,
+	orgId: string
+): Promise<string> {
+	// Check cache first
+	const cachedRegion = await getResourceRegion('sandbox', profileName, sandboxId);
+	if (cachedRegion) {
+		logger.trace(`[sandbox] Found cached region for ${sandboxId}: ${cachedRegion}`);
+		return cachedRegion;
+	}
+
+	// Fallback to API lookup using global client
+	logger.trace(`[sandbox] Cache miss for ${sandboxId}, fetching from API`);
+	const globalClient = await getGlobalCatalystAPIClient(logger, auth, profileName);
+
+	const sandbox = await sandboxGet(globalClient, { sandboxId, orgId });
+	if (!sandbox.region) {
+		tui.fatal(`Sandbox '${sandboxId}' has no region information`, ErrorCode.RESOURCE_NOT_FOUND);
+	}
+
+	// Cache the result
+	await setResourceRegion('sandbox', profileName, sandboxId, sandbox.region);
+	logger.trace(`[sandbox] Cached region for ${sandboxId}: ${sandbox.region}`);
+
+	return sandbox.region;
+}
+
+/**
+ * Cache the region for a sandbox after create/run operations
+ */
+export async function cacheSandboxRegion(
+	profileName = 'production',
+	sandboxId: string,
+	region: string
+): Promise<void> {
+	await setResourceRegion('sandbox', profileName, sandboxId, region);
+}
+
+/**
+ * Clear cached region for a sandbox after delete
+ */
+export async function clearSandboxRegionCache(
+	profileName = 'production',
+	sandboxId: string
+): Promise<void> {
+	await deleteResourceRegion('sandbox', profileName, sandboxId);
+}
+
 /**
  * Parse --file arguments and read file contents.
  *

package/src/cmd/cloud/scp/download.ts

@@ -3,6 +3,7 @@ import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { getIONHost } from '../../../config';
 import { getCommand } from '../../../command-prefix';
+import { getIdentifierRegion } from '../region-lookup';
 const args = z.object({
 	source: z.string().describe('the source file'),
 	destination: z.string().optional().describe('the destination file'),
@@ -36,7 +37,7 @@ export const downloadCommand = createSubcommand({
 			description: 'Download multiple files',
 		},
 	],
-	requires: { apiClient: true, auth: true, region: true },
+	requires: { apiClient: true, auth: true },
 	optional: { project: true },
 	prerequisites: ['cloud deploy'],
 	schema: {
@@ -51,7 +52,7 @@ export const downloadCommand = createSubcommand({
 	},
 
 	async handler(ctx) {
-		const { apiClient, args, opts, project, projectDir, config, region } = ctx;
+		const { apiClient, args, opts, project, projectDir, config, logger, auth, orgId } = ctx;
 
 		let identifier = opts?.identifier ?? project?.projectId;
 
@@ -59,6 +60,17 @@ export const downloadCommand = createSubcommand({
 			identifier = await tui.showProjectList(apiClient, true);
 		}
 
+		// Look up region from identifier (project/deployment)
+		const profileName = config?.name;
+		const region = await getIdentifierRegion(
+			logger,
+			auth,
+			apiClient,
+			profileName,
+			identifier,
+			orgId
+		);
+
 		const hostname = getIONHost(config, region);
 		const destination = args.destination ?? projectDir;
 

package/src/cmd/cloud/scp/upload.ts

@@ -3,6 +3,7 @@ import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { getIONHost } from '../../../config';
 import { getCommand } from '../../../command-prefix';
+import { getIdentifierRegion } from '../region-lookup';
 const args = z.object({
 	source: z.string().describe('the source file'),
 	destination: z
@@ -39,7 +40,7 @@ export const uploadCommand = createSubcommand({
 			description: 'Upload multiple files',
 		},
 	],
-	requires: { apiClient: true, auth: true, region: true },
+	requires: { apiClient: true, auth: true },
 	schema: {
 		args,
 		options,
@@ -54,7 +55,7 @@ export const uploadCommand = createSubcommand({
 	prerequisites: ['cloud deploy'],
 
 	async handler(ctx) {
-		const { apiClient, args, opts, project, projectDir, config, region } = ctx;
+		const { apiClient, args, opts, project, projectDir, config, logger, auth, orgId } = ctx;
 
 		let identifier = opts?.identifier ?? project?.projectId;
 
@@ -62,6 +63,17 @@ export const uploadCommand = createSubcommand({
 			identifier = await tui.showProjectList(apiClient, true);
 		}
 
+		// Look up region from identifier (project/deployment)
+		const profileName = config?.name;
+		const region = await getIdentifierRegion(
+			logger,
+			auth,
+			apiClient,
+			profileName,
+			identifier,
+			orgId
+		);
+
 		const hostname = getIONHost(config, region);
 		const destination = args.destination ?? '.';
 

package/src/cmd/cloud/session/get.ts

@@ -10,7 +10,7 @@ import {
 } from '@agentuity/server';
 import { getCommand } from '../../../command-prefix';
 import { ErrorCode } from '../../../errors';
-import { getCatalystAPIClient } from '../../../config';
+import { getGlobalCatalystAPIClient } from '../../../config';
 
 const SpanNodeSchema: z.ZodType<SpanNode> = z.lazy(() =>
 	z.object({
@@ -116,7 +116,7 @@ export const getSubcommand = createSubcommand({
 			description: 'Get a session by ID',
 		},
 	],
-	requires: { auth: true, region: true },
+	requires: { auth: true },
 	idempotent: true,
 	schema: {
 		args: z.object({
@@ -125,8 +125,8 @@ export const getSubcommand = createSubcommand({
 		response: SessionGetResponseSchema,
 	},
 	async handler(ctx) {
-		const { logger, auth, args, options, region } = ctx;
-		const catalystClient = getCatalystAPIClient(logger, auth, region);
+		const { logger, auth, args, options, config } = ctx;
+		const catalystClient = await getGlobalCatalystAPIClient(logger, auth, config?.name);
 
 		try {
 			const enriched = await sessionGet(catalystClient, { id: args.session_id });

package/src/cmd/cloud/session/list.ts

@@ -4,7 +4,7 @@ import * as tui from '../../../tui';
 import { sessionList } from '@agentuity/server';
 import { getCommand } from '../../../command-prefix';
 import { ErrorCode } from '../../../errors';
-import { getCatalystAPIClient } from '../../../config';
+import { getGlobalCatalystAPIClient } from '../../../config';
 
 const SessionListResponseSchema = z.array(
 	z.object({
@@ -55,7 +55,7 @@ export const listSubcommand = createSubcommand({
 		},
 	],
 	aliases: ['ls'],
-	requires: { auth: true, region: true },
+	requires: { auth: true },
 	optional: { project: true },
 	idempotent: true,
 	pagination: {
@@ -93,8 +93,8 @@ export const listSubcommand = createSubcommand({
 		return projectId ? `/projects/${encodeURIComponent(projectId)}/sessions` : undefined;
 	},
 	async handler(ctx) {
-		const { logger, auth, project, opts, options, region } = ctx;
-		const catalystClient = getCatalystAPIClient(logger, auth, region);
+		const { logger, auth, project, opts, options, config } = ctx;
+		const catalystClient = await getGlobalCatalystAPIClient(logger, auth, config?.name);
 
 		const projectId = opts.projectId || project?.projectId;
 

package/src/cmd/cloud/ssh.ts

@@ -3,6 +3,7 @@ import { createSubcommand } from '../../types';
 import * as tui from '../../tui';
 import { getIONHost } from '../../config';
 import { getCommand } from '../../command-prefix';
+import { getIdentifierRegion } from './region-lookup';
 const args = z.object({
 	identifier: z.string().optional().describe('The project, deployment, or sandbox id to use'),
 	command: z.string().optional().describe('The command to run'),
@@ -39,13 +40,13 @@ export const sshSubcommand = createSubcommand({
 		},
 	],
 	toplevel: true,
-	requires: { auth: true, apiClient: true, region: true },
+	requires: { auth: true, apiClient: true },
 	optional: { project: true },
 	prerequisites: ['cloud deploy'],
 	schema: { args, options },
 
 	async handler(ctx) {
-		const { apiClient, project, projectDir, args, config, opts, region } = ctx;
+		const { apiClient, project, projectDir, args, config, opts, logger, auth, orgId } = ctx;
 
 		let projectId = project?.projectId;
 		let identifier = args?.identifier;
@@ -66,6 +67,18 @@ export const sshSubcommand = createSubcommand({
 			projectId = await tui.showProjectList(apiClient, true);
 		}
 
+		// Look up region from identifier (project/deployment/sandbox)
+		const profileName = config?.name;
+		const targetIdentifier = identifier ?? projectId!;
+		const region = await getIdentifierRegion(
+			logger,
+			auth,
+			apiClient,
+			profileName,
+			targetIdentifier,
+			orgId
+		);
+
 		const hostname = getIONHost(config, region);
 
 		const cmd = ['ssh', `${identifier ?? projectId}@${hostname}`, command].filter(

package/src/cmd/cloud/storage/delete.ts

@@ -1,14 +1,15 @@
 import { z } from 'zod';
-import { listResources, deleteResources } from '@agentuity/server';
+import { listOrgResources, deleteResources } from '@agentuity/server';
 import enquirer from 'enquirer';
 import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
-import { getCatalystAPIClient } from '../../../config';
+import { getGlobalCatalystAPIClient, getCatalystAPIClient } from '../../../config';
 import { getCommand } from '../../../command-prefix';
 import { isDryRunMode, outputDryRun } from '../../../explain';
 import { ErrorCode } from '../../../errors';
 import { createS3Client } from './utils';
 import { removeResourceEnvVars } from '../../../env-util';
+import { getResourceInfo, setResourceInfo, deleteResourceRegion } from '../../../cache';
 
 export const deleteSubcommand = createSubcommand({
 	name: 'delete',
@@ -16,7 +17,8 @@ export const deleteSubcommand = createSubcommand({
 	description: 'Delete a storage resource or file',
 	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth', 'requires-deployment'],
 	idempotent: false,
-	requires: { auth: true, org: true, region: true },
+	requires: { auth: true },
+	optional: { org: true },
 	examples: [
 		{
 			command: getCommand('cloud storage delete my-bucket'),
@@ -50,19 +52,50 @@ export const deleteSubcommand = createSubcommand({
 	},
 
 	async handler(ctx) {
-		const { logger, args, opts, orgId, region, auth, options } = ctx;
+		const { logger, args, opts, auth, options, config } = ctx;
 
-		const catalystClient = getCatalystAPIClient(logger, auth, region);
+		const profileName = config?.name ?? 'production';
+		const catalystClient = await getGlobalCatalystAPIClient(logger, auth, profileName);
+
+		let bucketName = args.name;
+
+		// If bucket name provided, try cache first for orgId
+		let orgId = ctx.orgId;
+		if (bucketName && !orgId) {
+			const cachedInfo = await getResourceInfo('bucket', profileName, bucketName);
+			orgId = cachedInfo?.orgId;
+		}
+
+		// For interactive selection (no bucket name), we need orgId
+		if (!bucketName && !orgId) {
+			tui.fatal(
+				'Organization required for interactive bucket selection. Specify --org-id or provide bucket name.',
+				ErrorCode.INVALID_ARGUMENT
+			);
+		}
+
+		// If we still don't have orgId and have a bucket name, error out
+		if (!orgId) {
+			tui.fatal(
+				`Organization not found for bucket '${bucketName}'. Run 'agentuity cloud storage list' first or specify --org-id.`,
+				ErrorCode.INVALID_ARGUMENT
+			);
+		}
 
 		const resources = await tui.spinner({
-			message: `Fetching storage for ${orgId} in ${region}`,
+			message: `Fetching storage for ${orgId}`,
 			clearOnSuccess: true,
 			callback: async () => {
-				return listResources(catalystClient, orgId, region!);
+				return listOrgResources(catalystClient, { type: 's3', orgId });
 			},
 		});
 
-		let bucketName = args.name;
+		// Cache all fetched buckets
+		for (const s3 of resources.s3) {
+			if (s3.cloud_region) {
+				await setResourceInfo('bucket', profileName, s3.bucket_name, s3.cloud_region, orgId);
+			}
+		}
 
 		if (!bucketName) {
 			if (resources.s3.length === 0) {
@@ -155,9 +188,22 @@ export const deleteSubcommand = createSubcommand({
 		}
 
 		// Otherwise, delete the bucket
+		// Find the bucket to get its region
+		const bucketToDelete = resources.s3.find((s3) => s3.bucket_name === bucketName);
+		if (!bucketToDelete) {
+			tui.fatal(`Storage bucket '${bucketName}' not found`, ErrorCode.RESOURCE_NOT_FOUND);
+		}
+		if (!bucketToDelete.cloud_region) {
+			tui.fatal(
+				`Storage bucket '${bucketName}' is missing region information`,
+				ErrorCode.RESOURCE_NOT_FOUND
+			);
+		}
+		const region = bucketToDelete.cloud_region;
+
 		// Handle dry-run mode
 		if (isDryRunMode(options)) {
-			outputDryRun(`Would delete storage bucket: ${bucketName}`, options);
+			outputDryRun(`Would delete storage bucket: ${bucketName} (region: ${region})`, options);
 			if (!options.json) {
 				tui.newline();
 				tui.info('[DRY RUN] Storage bucket deletion skipped');
@@ -184,11 +230,13 @@ export const deleteSubcommand = createSubcommand({
 			}
 		}
 
+		// Use regional client for the delete operation
+		const regionalClient = getCatalystAPIClient(logger, auth, region);
 		const deleted = await tui.spinner({
 			message: `Deleting storage bucket ${bucketName}`,
 			clearOnSuccess: true,
 			callback: async () => {
-				return deleteResources(catalystClient, orgId, region!, [
+				return deleteResources(regionalClient, orgId, region, [
 					{ type: 's3', name: bucketName },
 				]);
 			},
@@ -197,6 +245,9 @@ export const deleteSubcommand = createSubcommand({
 		if (deleted.length > 0) {
 			const resource = deleted[0];
 
+			// Clear cache entry for deleted bucket
+			await deleteResourceRegion('bucket', profileName, resource.name);
+
 			// Remove env vars from .env if running inside a project
 			if (ctx.projectDir && resource.env_keys.length > 0) {
 				await removeResourceEnvVars(ctx.projectDir, resource.env_keys);

package/src/cmd/cloud/storage/download.ts

@@ -1,17 +1,19 @@
 import { z } from 'zod';
-import { listResources } from '@agentuity/server';
+import { listOrgResources } from '@agentuity/server';
 import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
-import { getCatalystAPIClient } from '../../../config';
+import { getGlobalCatalystAPIClient } from '../../../config';
 import { getCommand } from '../../../command-prefix';
 import { ErrorCode } from '../../../errors';
 import { createS3Client } from './utils';
+import { getResourceInfo, setResourceInfo } from '../../../cache';
 
 export const downloadSubcommand = createSubcommand({
 	name: 'download',
 	description: 'Download a file from storage bucket',
 	tags: ['read-only', 'requires-auth'],
-	requires: { auth: true, org: true, region: true },
+	requires: { auth: true },
+	optional: { org: true },
 	idempotent: true,
 	examples: [
 		{
@@ -51,21 +53,44 @@ export const downloadSubcommand = createSubcommand({
 	},
 
 	async handler(ctx) {
-		const { logger, args, opts, options, orgId, region, auth } = ctx;
+		const { logger, args, opts, options, auth, config } = ctx;
 
-		const catalystClient = getCatalystAPIClient(logger, auth, region);
+		const profileName = config?.name ?? 'production';
+		const catalystClient = await getGlobalCatalystAPIClient(logger, auth, profileName);
+
+		// Check cache first for orgId
+		const cachedInfo = await getResourceInfo('bucket', profileName, args.name);
+		const orgId = ctx.orgId ?? cachedInfo?.orgId;
+
+		if (!orgId) {
+			tui.fatal(
+				`Organization not found for bucket '${args.name}'. Run 'agentuity cloud storage list' first or specify --org-id.`,
+				ErrorCode.INVALID_ARGUMENT
+			);
+		}
 
 		// Fetch bucket credentials
 		const resources = await tui.spinner({
 			message: `Fetching credentials for ${args.name}`,
 			clearOnSuccess: true,
 			callback: async () => {
-				return listResources(catalystClient, orgId, region);
+				return listOrgResources(catalystClient, { type: 's3', orgId });
 			},
 		});
 
 		const bucket = resources.s3.find((s3) => s3.bucket_name === args.name);
 
+		// Cache the bucket info for future lookups
+		if (bucket?.cloud_region) {
+			await setResourceInfo(
+				'bucket',
+				profileName,
+				bucket.bucket_name,
+				bucket.cloud_region,
+				orgId
+			);
+		}
+
 		if (!bucket) {
 			tui.fatal(`Storage bucket '${args.name}' not found`, ErrorCode.RESOURCE_NOT_FOUND);
 		}