@agentuity/cli 0.1.9 → 0.1.11

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

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { createCommand } from '../../../../types';
 import * as tui from '../../../../tui';
-import { createSandboxClient } from '../util';
+import { getSandboxRegion, createSandboxClient } from '../util';
 import { getCommand } from '../../../../command-prefix';
 import { snapshotCreate } from '@agentuity/server';
 
@@ -23,7 +23,7 @@ export const createSubcommand = createCommand({
 	name: 'create',
 	description: 'Create a snapshot from a sandbox',
 	tags: ['slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	examples: [
 		{
 			command: getCommand('cloud sandbox snapshot create sbx_abc123'),
@@ -34,7 +34,9 @@ export const createSubcommand = createCommand({
 			description: 'Create a tagged snapshot',
 		},
 		{
-			command: getCommand('cloud sandbox snapshot create sbx_abc123 --name "My Snapshot" --description "Initial setup"'),
+			command: getCommand(
+				'cloud sandbox snapshot create sbx_abc123 --name "My Snapshot" --description "Initial setup"'
+			),
 			description: 'Create a named snapshot with description',
 		},
 	],
@@ -54,7 +56,7 @@ export const createSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args, opts, options, auth, region, logger, orgId } = ctx;
+		const { args, opts, options, auth, logger, orgId, config } = ctx;
 
 		if (opts.name && !SNAPSHOT_NAME_REGEX.test(opts.name)) {
 			logger.fatal(
@@ -64,7 +66,9 @@ export const createSubcommand = createCommand({
 
 		if (opts.tag) {
 			if (opts.tag.length > MAX_SNAPSHOT_TAG_LENGTH) {
-				logger.fatal(`Invalid snapshot tag: must be at most ${MAX_SNAPSHOT_TAG_LENGTH} characters`);
+				logger.fatal(
+					`Invalid snapshot tag: must be at most ${MAX_SNAPSHOT_TAG_LENGTH} characters`
+				);
 			}
 			if (!SNAPSHOT_TAG_REGEX.test(opts.tag)) {
 				logger.fatal(
@@ -73,6 +77,8 @@ export const createSubcommand = createCommand({
 			}
 		}
 
+		const profileName = config?.name;
+		const region = await getSandboxRegion(logger, auth, profileName, args.sandboxId, orgId);
 		const client = createSandboxClient(logger, auth, region);
 
 		const snapshot = await snapshotCreate(client, {

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

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 import { createCommand } from '../../../../types';
 import * as tui from '../../../../tui';
-import { createSandboxClient } from '../util';
 import { getCommand } from '../../../../command-prefix';
 import { snapshotDelete } from '@agentuity/server';
+import { getGlobalCatalystAPIClient } from '../../../../config';
 
 const SnapshotDeleteResponseSchema = z.object({
 	success: z.boolean().describe('Whether the operation succeeded'),
@@ -16,7 +16,7 @@ export const deleteSubcommand = createCommand({
 	aliases: ['del', 'rm', 'remove'],
 	description: 'Delete a snapshot',
 	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	idempotent: true,
 	examples: [
 		{
@@ -39,7 +39,7 @@ export const deleteSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args, options, opts, auth, region, logger, orgId } = ctx;
+		const { args, options, opts, auth, logger, orgId, config } = ctx;
 
 		if (!opts.confirm) {
 			const confirmed = await tui.confirm(`Delete snapshot "${args.snapshotId}"?`, false);
@@ -53,7 +53,7 @@ export const deleteSubcommand = createCommand({
 			}
 		}
 
-		const client = createSandboxClient(logger, auth, region);
+		const client = await getGlobalCatalystAPIClient(logger, auth, config?.name);
 
 		await snapshotDelete(client, {
 			snapshotId: args.snapshotId,

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

@@ -0,0 +1,134 @@
+import { z } from 'zod';
+import { createCommand } from '../../../../types';
+import { getCommand } from '../../../../command-prefix';
+
+const TEMPLATE_YAML = `# yaml-language-server: $schema=https://agentuity.dev/schema/cli/v1/agentuity-snapshot.json
+#
+# Agentuity Snapshot Build File
+# =============================
+# This file defines a reproducible sandbox environment.
+# Build with: agentuity cloud sandbox snapshot build <directory>
+#
+# For documentation, see: https://agentuity.dev/Services/Sandbox
+
+# Required: Schema version (must be 1)
+version: 1
+
+# Required: Runtime environment
+# Format: name:tag (e.g., bun:1, node:20, python:3.12)
+# Run 'agentuity cloud sandbox runtime list' to see available runtimes
+runtime: bun:1
+
+# Optional: Snapshot name (alphanumeric, underscores, dashes only)
+# If not provided, a unique name will be auto-generated
+# name: my-snapshot
+
+# Optional: Human-readable description
+# Can be overridden with --description flag
+description: My sandbox snapshot
+
+# Optional: Apt packages to install
+# Packages are validated against Debian stable repositories
+# Supports version pinning: package=version or package=version* (prefix match)
+# dependencies:
+#   - curl
+#   - ffmpeg
+#   - imagemagick=8:6.9*
+
+# Optional: Files to include from the build context directory
+# Supports glob patterns and negative patterns (prefix with !)
+# Files are placed in /home/agentuity/ in the sandbox
+# files:
+#   - "*.js"              # All JS files in root
+#   - src/**              # All files in src/ recursively
+#   - config/*.json       # All JSON files in config/
+#   - "!**/*.test.js"     # Exclude test files
+#   - "!node_modules/**"  # Exclude node_modules
+
+# Optional: Environment variables
+# Use \${VAR} syntax for build-time substitution via --env flag
+# env:
+#   NODE_ENV: production
+#   API_URL: https://api.example.com
+#   SECRET_KEY: \${SECRET_KEY}  # Substituted from: --env SECRET_KEY=value
+
+# Optional: Custom metadata
+# Use \${VAR} syntax for build-time substitution via --metadata flag
+# Stored with the snapshot for reference
+# metadata:
+#   version: \${VERSION}   # Substituted from: --metadata VERSION=1.0.0
+#   author: team-name
+#   build_date: \${BUILD_DATE}
+`;
+
+const TEMPLATE_JSON = {
+	$schema: 'https://agentuity.dev/schema/cli/v1/agentuity-snapshot.json',
+	version: 1,
+	runtime: 'bun:1',
+	name: 'my-snapshot',
+	description: 'My sandbox snapshot',
+	dependencies: ['curl'],
+	files: ['src/**', '*.js', '!**/*.test.js'],
+	env: {
+		NODE_ENV: 'production',
+	},
+	metadata: {
+		version: '1.0.0',
+	},
+};
+
+const GenerateResponseSchema = z.object({
+	format: z.enum(['yaml', 'json']).describe('Output format'),
+	content: z.string().describe('Generated template content'),
+});
+
+export const generateSubcommand = createCommand({
+	name: 'generate',
+	aliases: ['gen', 'init'],
+	description: 'Generate a template snapshot build file',
+	tags: [],
+	requires: {},
+	examples: [
+		{
+			command: getCommand('cloud sandbox snapshot generate'),
+			description: 'Generate a YAML template (default)',
+		},
+		{
+			command: getCommand('cloud sandbox snapshot generate --format json'),
+			description: 'Generate a JSON template',
+		},
+		{
+			command: getCommand('cloud sandbox snapshot generate > agentuity-snapshot.yaml'),
+			description: 'Save template to a file',
+		},
+	],
+	schema: {
+		options: z.object({
+			format: z.enum(['yaml', 'json']).default('yaml').describe('Output format (yaml or json)'),
+		}),
+		response: GenerateResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { opts, options } = ctx;
+		const format = opts.format;
+
+		let content: string;
+		if (format === 'json') {
+			content = JSON.stringify(TEMPLATE_JSON, null, 2);
+		} else {
+			content = TEMPLATE_YAML;
+		}
+
+		if (!options.json) {
+			console.log(content);
+		}
+
+		return {
+			format,
+			content,
+		};
+	},
+});
+
+export default generateSubcommand;

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(),
@@ -21,6 +21,7 @@ const SandboxInfoSchema = z.object({
 
 const SnapshotGetResponseSchema = z.object({
 	snapshotId: z.string().describe('Snapshot ID'),
+	name: z.string().describe('Snapshot name'),
 	tag: z.string().nullable().optional().describe('Snapshot tag'),
 	sizeBytes: z.number().describe('Snapshot size in bytes'),
 	fileCount: z.number().describe('Number of files'),
@@ -28,6 +29,11 @@ const SnapshotGetResponseSchema = z.object({
 	createdAt: z.string().describe('Creation timestamp'),
 	downloadUrl: z.string().optional().describe('Presigned download URL'),
 	files: z.array(SnapshotFileSchema).nullable().optional().describe('Files in snapshot'),
+	userMetadata: z
+		.record(z.string(), z.string())
+		.nullable()
+		.optional()
+		.describe('User-defined metadata'),
 	sandboxes: z
 		.array(SandboxInfoSchema)
 		.optional()
@@ -39,7 +45,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 +60,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,
@@ -73,6 +79,7 @@ export const getSubcommand = createCommand({
 
 		if (!options.json) {
 			tui.info(`Snapshot: ${tui.bold(snapshot.snapshotId)}`);
+			console.log(`  ${tui.muted('Name:')}    ${snapshot.name}`);
 			if (snapshot.tag) {
 				console.log(`  ${tui.muted('Tag:')}     ${snapshot.tag}`);
 			}
@@ -83,6 +90,18 @@ export const getSubcommand = createCommand({
 				console.log(`  ${tui.muted('Parent:')}  ${snapshot.parentSnapshotId}`);
 			}
 
+			if (
+				snapshot.userMetadata &&
+				typeof snapshot.userMetadata === 'object' &&
+				Object.keys(snapshot.userMetadata).length > 0
+			) {
+				console.log('');
+				tui.info('Metadata:');
+				for (const [key, value] of Object.entries(snapshot.userMetadata)) {
+					console.log(`  ${tui.muted('•')} ${key}=${value}`);
+				}
+			}
+
 			if (snapshot.files && snapshot.files.length > 0) {
 				console.log('');
 				tui.info('Files:');

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

@@ -4,6 +4,8 @@ import { listSubcommand } from './list';
 import { getSubcommand } from './get';
 import { deleteSubcommand } from './delete';
 import { tagSubcommand } from './tag';
+import { buildSubcommand } from './build';
+import { generateSubcommand } from './generate';
 import { getCommand } from '../../../../command-prefix';
 
 export const snapshotCommand = createCommand({
@@ -20,9 +22,25 @@ export const snapshotCommand = createCommand({
 			command: getCommand('cloud sandbox snapshot list'),
 			description: 'List all snapshots',
 		},
+		{
+			command: getCommand('cloud sandbox snapshot build .'),
+			description: 'Build a snapshot from a declarative file',
+		},
+		{
+			command: getCommand('cloud sandbox snapshot generate > agentuity-snapshot.yaml'),
+			description: 'Generate a template build file',
+		},
+	],
+	subcommands: [
+		createSubcommand,
+		listSubcommand,
+		getSubcommand,
+		deleteSubcommand,
+		tagSubcommand,
+		buildSubcommand,
+		generateSubcommand,
 	],
-	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,9 +1,9 @@
 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(),
@@ -26,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'),
@@ -47,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,

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

@@ -1,9 +1,9 @@
 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;
@@ -17,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'),
@@ -40,8 +40,8 @@ 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');
@@ -49,7 +49,9 @@ export const tagSubcommand = createCommand({
 
 		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`);
+				logger.fatal(
+					`Invalid snapshot tag: must be at most ${MAX_SNAPSHOT_TAG_LENGTH} characters`
+				);
 			}
 			if (!SNAPSHOT_TAG_REGEX.test(args.tag)) {
 				logger.fatal(

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;