@agentuity/cli 0.1.8 → 0.1.10

package/src/cmd/cloud/sandbox/execution/list.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 { executionList } from '@agentuity/server';
 
@@ -25,7 +25,7 @@ export const listSubcommand = createCommand({
 	aliases: ['ls'],
 	description: 'List executions for a sandbox',
 	tags: ['read-only', 'fast', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	idempotent: true,
 	examples: [
 		{
@@ -48,7 +48,8 @@ export const listSubcommand = 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 result = await executionList(client, {

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

@@ -1,9 +1,10 @@
 import { z } from 'zod';
 import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
-import { createSandboxClient } from './util';
+import { cacheSandboxRegion } from './util';
 import { getCommand } from '../../../command-prefix';
 import { sandboxGet } from '@agentuity/server';
+import { getGlobalCatalystAPIClient } from '../../../config';
 
 const SandboxResourcesSchema = z.object({
 	memory: z.string().optional().describe('Memory limit (e.g., "512Mi", "1Gi")'),
@@ -13,9 +14,13 @@ const SandboxResourcesSchema = z.object({
 
 const SandboxGetResponseSchema = z.object({
 	sandboxId: z.string().describe('Sandbox ID'),
+	name: z.string().optional().describe('Sandbox name'),
+	description: z.string().optional().describe('Sandbox description'),
 	status: z.string().describe('Current status'),
 	createdAt: z.string().describe('Creation timestamp'),
 	region: z.string().optional().describe('Region where sandbox is running'),
+	runtimeId: z.string().optional().describe('Runtime ID'),
+	runtimeName: z.string().optional().describe('Runtime name'),
 	snapshotId: z.string().optional().describe('Snapshot ID sandbox was created from'),
 	snapshotTag: z.string().optional().describe('Snapshot tag sandbox was created from'),
 	executions: z.number().describe('Number of executions'),
@@ -31,7 +36,7 @@ export const getSubcommand = createCommand({
 	aliases: ['info', 'show'],
 	description: 'Get information about a sandbox',
 	tags: ['read-only', 'fast', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	idempotent: true,
 	examples: [
 		{
@@ -47,11 +52,16 @@ 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 result = await sandboxGet(client, { sandboxId: args.sandboxId, orgId });
 
+		// Cache the region for future lookups
+		if (result.region) {
+			await cacheSandboxRegion(config?.name, args.sandboxId, result.region);
+		}
+
 		if (!options.json) {
 			const statusColor =
 				result.status === 'running'
@@ -63,8 +73,17 @@ export const getSubcommand = createCommand({
 							: tui.colorMuted;
 
 			console.log(`${tui.muted('Sandbox:')}         ${tui.bold(result.sandboxId)}`);
+			if (result.name) {
+				console.log(`${tui.muted('Name:')}            ${result.name}`);
+			}
+			if (result.description) {
+				console.log(`${tui.muted('Description:')}     ${result.description}`);
+			}
 			console.log(`${tui.muted('Status:')}          ${statusColor(result.status)}`);
 			console.log(`${tui.muted('Created:')}         ${result.createdAt}`);
+			if (result.runtimeName) {
+				console.log(`${tui.muted('Runtime:')}         ${result.runtimeName}`);
+			}
 			if (result.region) {
 				console.log(`${tui.muted('Region:')}          ${result.region}`);
 			}
@@ -108,9 +127,13 @@ export const getSubcommand = createCommand({
 
 		return {
 			sandboxId: result.sandboxId,
+			name: result.name,
+			description: result.description,
 			status: result.status,
 			createdAt: result.createdAt,
 			region: result.region,
+			runtimeId: result.runtimeId,
+			runtimeName: result.runtimeName,
 			snapshotId: result.snapshotId,
 			snapshotTag: result.snapshotTag,
 			executions: result.executions,

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

@@ -6,6 +6,7 @@ import { listSubcommand } from './list';
 import { getSubcommand } from './get';
 import { deleteSubcommand } from './delete';
 import { snapshotCommand } from './snapshot';
+import { runtimeCommand } from './runtime';
 import { cpSubcommand } from './cp';
 import { command as executionCommand } from './execution';
 import { mkdirSubcommand } from './mkdir';
@@ -44,6 +45,7 @@ export const command = createCommand({
 		getSubcommand,
 		deleteSubcommand,
 		snapshotCommand,
+		runtimeCommand,
 		cpSubcommand,
 		executionCommand,
 		mkdirSubcommand,
@@ -54,7 +56,7 @@ export const command = createCommand({
 		uploadSubcommand,
 		envSubcommand,
 	],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 });
 
 export default command;

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

@@ -3,14 +3,18 @@ import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
 import { getCommand } from '../../../command-prefix';
 import { sandboxList } from '@agentuity/server';
-import { createSandboxClient } from './util';
+import { getGlobalCatalystAPIClient } from '../../../config';
 import type { SandboxStatus } from '@agentuity/core';
 
 const SandboxInfoSchema = z.object({
 	sandboxId: z.string().describe('Sandbox ID'),
+	name: z.string().optional().describe('Sandbox name'),
+	description: z.string().optional().describe('Sandbox description'),
 	status: z.string().describe('Current status'),
 	createdAt: z.string().describe('Creation timestamp'),
 	region: z.string().optional().describe('Region where sandbox is running'),
+	runtimeId: z.string().optional().describe('Runtime ID'),
+	runtimeName: z.string().optional().describe('Runtime name'),
 	snapshotId: z.string().optional().describe('Snapshot ID sandbox was created from'),
 	snapshotTag: z.string().optional().describe('Snapshot tag sandbox was created from'),
 	executions: z.number().describe('Number of executions'),
@@ -26,7 +30,7 @@ export const listSubcommand = createCommand({
 	aliases: ['ls'],
 	description: 'List sandboxes with optional filtering',
 	tags: ['read-only', 'slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	optional: { project: true },
 	idempotent: true,
 	pagination: {
@@ -70,8 +74,8 @@ export const listSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { opts, options, auth, project, region, logger, orgId } = ctx;
-		const client = createSandboxClient(logger, auth, region);
+		const { opts, options, auth, project, logger, orgId, config } = ctx;
+		const client = await getGlobalCatalystAPIClient(logger, auth, config?.name);
 
 		const projectId = opts.projectId || project?.projectId;
 
@@ -88,22 +92,21 @@ export const listSubcommand = createCommand({
 				tui.info('No sandboxes found');
 			} else {
 				const tableData = result.sandboxes.map((sandbox) => {
-					const snapshotDisplay = sandbox.snapshotTag
-						? `${sandbox.snapshotTag} (${sandbox.snapshotId})`
-						: sandbox.snapshotId || '-';
 					return {
 						ID: sandbox.sandboxId,
+						Name: sandbox.name || '-',
+						Runtime: sandbox.runtimeName || '-',
 						Status: sandbox.status,
 						'Created At': sandbox.createdAt,
-						Snapshot: snapshotDisplay,
 						Executions: sandbox.executions,
 					};
 				});
 				tui.table(tableData, [
 					{ name: 'ID', alignment: 'left' },
+					{ name: 'Name', alignment: 'left' },
+					{ name: 'Runtime', alignment: 'left' },
 					{ name: 'Status', alignment: 'left' },
 					{ name: 'Created At', alignment: 'left' },
-					{ name: 'Snapshot', alignment: 'left' },
 					{ name: 'Executions', alignment: 'right' },
 				]);
 
@@ -114,9 +117,13 @@ export const listSubcommand = createCommand({
 		return {
 			sandboxes: result.sandboxes.map((s) => ({
 				sandboxId: s.sandboxId,
+				name: s.name,
+				description: s.description,
 				status: s.status,
 				createdAt: s.createdAt,
 				region: s.region,
+				runtimeId: s.runtimeId,
+				runtimeName: s.runtimeName,
 				snapshotId: s.snapshotId,
 				snapshotTag: s.snapshotTag,
 				executions: s.executions,

package/src/cmd/cloud/sandbox/ls.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 { sandboxListFiles } from '@agentuity/server';
 
@@ -23,7 +23,7 @@ export const lsSubcommand = createCommand({
 	aliases: ['lsf'],
 	description: 'List files in a sandbox directory',
 	tags: ['slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	examples: [
 		{
 			command: getCommand('cloud sandbox files sbx_abc123'),
@@ -61,7 +61,8 @@ export const lsSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args, opts, options, auth, region, logger, orgId } = ctx;
+		const { args, opts, options, auth, config, logger, orgId } = ctx;
+		const region = await getSandboxRegion(logger, auth, config?.name, args.sandboxId, orgId);
 		const client = createSandboxClient(logger, auth, region);
 
 		const result = await sandboxListFiles(client, {

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

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
-import { createSandboxClient } from './util';
+import { createSandboxClient, getSandboxRegion } from './util';
 import { getCommand } from '../../../command-prefix';
 import { sandboxMkDir } from '@agentuity/server';
 
@@ -14,7 +14,7 @@ export const mkdirSubcommand = createCommand({
 	name: 'mkdir',
 	description: 'Create a directory in a sandbox',
 	tags: ['slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	examples: [
 		{
 			command: getCommand('cloud sandbox mkdir sbx_abc123 /path/to/dir'),
@@ -44,7 +44,8 @@ export const mkdirSubcommand = 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);
 
 		await sandboxMkDir(client, {

package/src/cmd/cloud/sandbox/rm.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 { sandboxRmFile } from '@agentuity/server';
 
@@ -14,7 +14,7 @@ export const rmSubcommand = createCommand({
 	name: 'rm',
 	description: 'Remove a file from a sandbox',
 	tags: ['slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	examples: [
 		{
 			command: getCommand('cloud sandbox rm sbx_abc123 /path/to/file.txt'),
@@ -31,7 +31,8 @@ export const rmSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args, options, auth, region, logger, orgId } = ctx;
+		const { args, options, auth, logger, orgId, config } = ctx;
+		const region = await getSandboxRegion(logger, auth, config?.name, args.sandboxId, orgId);
 		const client = createSandboxClient(logger, auth, region);
 
 		await sandboxRmFile(client, {

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

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
-import { createSandboxClient } from './util';
+import { createSandboxClient, getSandboxRegion } from './util';
 import { getCommand } from '../../../command-prefix';
 import { sandboxRmDir } from '@agentuity/server';
 
@@ -14,7 +14,7 @@ export const rmdirSubcommand = createCommand({
 	name: 'rmdir',
 	description: 'Remove a directory from a sandbox',
 	tags: ['slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	examples: [
 		{
 			command: getCommand('cloud sandbox rmdir sbx_abc123 /path/to/dir'),
@@ -44,7 +44,8 @@ export const rmdirSubcommand = 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);
 
 		await sandboxRmDir(client, {

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

@@ -2,9 +2,11 @@ import { z } from 'zod';
 import { Writable } from 'node:stream';
 import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
-import { createSandboxClient, parseFileArgs } from './util';
+import { createSandboxClient, parseFileArgs, cacheSandboxRegion } from './util';
 import { getCommand } from '../../../command-prefix';
 import { sandboxRun } from '@agentuity/server';
+import { validateAptDependencies } from '../../../utils/apt-validator';
+import { ErrorCode } from '../../../errors';
 
 const SandboxRunResponseSchema = z.object({
 	sandboxId: z.string().describe('Sandbox ID'),
@@ -37,6 +39,10 @@ export const runSubcommand = createCommand({
 			command: z.array(z.string()).describe('Command and arguments to execute'),
 		}),
 		options: z.object({
+			runtime: z.string().optional().describe('Runtime name (e.g., "bun:1", "python:3.14")'),
+			runtimeId: z.string().optional().describe('Runtime ID (e.g., "srt_xxx")'),
+			name: z.string().optional().describe('Sandbox name'),
+			description: z.string().optional().describe('Sandbox description'),
 			memory: z.string().optional().describe('Memory limit (e.g., "500Mi", "1Gi")'),
 			cpu: z.string().optional().describe('CPU limit in millicores (e.g., "500m", "1000m")'),
 			disk: z.string().optional().describe('Disk limit (e.g., "500Mi", "1Gi")'),
@@ -62,10 +68,53 @@ export const runSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args, opts, options, auth, region, logger, orgId } = ctx;
+		const { args, opts, options, auth, region, config, logger, orgId } = ctx;
 		const client = createSandboxClient(logger, auth, region);
 		const started = Date.now();
 
+		// Validate apt dependencies before running sandbox
+		if (opts.dependency && opts.dependency.length > 0) {
+			const aptValidation = await tui.spinner({
+				message: 'Validating apt dependencies...',
+				type: 'simple',
+				callback: async () => {
+					return await validateAptDependencies(opts.dependency!, region, config, logger);
+				},
+			});
+
+			if (aptValidation.invalid.length > 0) {
+				if (options.json) {
+					return {
+						sandboxId: '',
+						exitCode: 1,
+						durationMs: 0,
+						errors: aptValidation.invalid.map((pkg) => ({
+							type: 'invalid-apt-dependency',
+							package: pkg.package,
+							error: pkg.error,
+							searchUrl: pkg.searchUrl,
+							availableVersions: pkg.availableVersions,
+						})),
+					} as never;
+				}
+
+				tui.error('Invalid apt dependencies:');
+				tui.newline();
+				for (const pkg of aptValidation.invalid) {
+					tui.bullet(`${tui.bold(pkg.package)}: ${pkg.error}`);
+					if (pkg.availableVersions && pkg.availableVersions.length > 0) {
+						tui.muted(`    Available versions: ${pkg.availableVersions.join(', ')}`);
+					}
+					tui.muted(`    Search: ${tui.link(pkg.searchUrl)}`);
+				}
+				tui.newline();
+				tui.fatal(
+					'Fix the apt dependencies and try again. Search for valid packages at: https://packages.debian.org/stable/',
+					ErrorCode.CONFIG_INVALID
+				);
+			}
+		}
+
 		const envMap: Record<string, string> = {};
 		if (opts.env) {
 			for (const e of opts.env) {
@@ -102,6 +151,10 @@ export const runSubcommand = createCommand({
 		try {
 			const result = await sandboxRun(client, {
 				options: {
+					runtime: opts.runtime,
+					runtimeId: opts.runtimeId,
+					name: opts.name,
+					description: opts.description,
 					command: {
 						exec: args.command,
 						files: hasFiles ? files : undefined,
@@ -131,6 +184,9 @@ export const runSubcommand = createCommand({
 				logger,
 			});
 
+			// Cache the region for future lookups (sandbox is destroyed after run but cache helps with lookups during execution)
+			await cacheSandboxRegion(config?.name, result.sandboxId, region);
+
 			const duration = Date.now() - started;
 			const output = outputChunks.join('');
 

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

@@ -0,0 +1,20 @@
+import { createCommand } from '../../../../types';
+import { listSubcommand } from './list';
+import { getCommand } from '../../../../command-prefix';
+
+export const runtimeCommand = createCommand({
+	name: 'runtime',
+	aliases: ['rt'],
+	description: 'Manage sandbox runtimes',
+	tags: ['slow', 'requires-auth'],
+	examples: [
+		{
+			command: getCommand('cloud sandbox runtime list'),
+			description: 'List all available runtimes',
+		},
+	],
+	subcommands: [listSubcommand],
+	requires: { auth: true, org: true },
+});
+
+export default runtimeCommand;

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

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+import { createCommand } from '../../../../types';
+import * as tui from '../../../../tui';
+import { getCommand } from '../../../../command-prefix';
+import { runtimeList } from '@agentuity/server';
+import { getGlobalCatalystAPIClient } from '../../../../config';
+
+const RuntimeInfoSchema = z.object({
+	id: z.string().describe('Runtime ID'),
+	name: z.string().describe('Runtime name'),
+	description: z.string().optional().describe('Runtime description'),
+});
+
+const RuntimeListResponseSchema = z.object({
+	runtimes: z.array(RuntimeInfoSchema).describe('List of runtimes'),
+	total: z.number().describe('Total number of runtimes'),
+});
+
+export const listSubcommand = createCommand({
+	name: 'list',
+	aliases: ['ls'],
+	description: 'List available sandbox runtimes',
+	tags: ['read-only', 'slow', 'requires-auth'],
+	requires: { auth: true, org: true },
+	idempotent: true,
+	examples: [
+		{
+			command: getCommand('cloud sandbox runtime list'),
+			description: 'List all available runtimes',
+		},
+	],
+	schema: {
+		options: z.object({
+			limit: z.number().optional().describe('Maximum number of results'),
+			offset: z.number().optional().describe('Offset for pagination'),
+		}),
+		response: RuntimeListResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { opts, options, auth, logger, orgId, config } = ctx;
+		const client = await getGlobalCatalystAPIClient(logger, auth, config?.name);
+
+		const result = await runtimeList(client, {
+			orgId,
+			limit: opts.limit,
+			offset: opts.offset,
+		});
+
+		if (!options.json) {
+			if (result.runtimes.length === 0) {
+				tui.info('No runtimes available');
+			} else {
+				const tableData = result.runtimes.map((runtime) => {
+					return {
+						ID: runtime.id,
+						Name: runtime.name,
+						Description: runtime.description ?? '-',
+					};
+				});
+				tui.table(tableData, [
+					{ name: 'ID', alignment: 'left' },
+					{ name: 'Name', alignment: 'left' },
+					{ name: 'Description', alignment: 'left' },
+				]);
+
+				tui.info(`Total: ${result.total} ${tui.plural(result.total, 'runtime', 'runtimes')}`);
+			}
+		}
+
+		return result;
+	},
+});
+
+export default listSubcommand;

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

@@ -1,13 +1,19 @@
 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';
 
+const SNAPSHOT_NAME_REGEX = /^[a-zA-Z0-9_-]+$/;
+const SNAPSHOT_TAG_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+const MAX_SNAPSHOT_TAG_LENGTH = 128;
+
 const SnapshotCreateResponseSchema = z.object({
 	snapshotId: z.string().describe('Snapshot ID'),
-	tag: z.string().optional().nullable().describe('Snapshot tag'),
+	name: z.string().describe('Snapshot display name'),
+	description: z.string().optional().nullable().describe('Snapshot description'),
+	tag: z.string().optional().nullable().describe('Snapshot tag (defaults to "latest")'),
 	sizeBytes: z.number().describe('Snapshot size in bytes'),
 	fileCount: z.number().describe('Number of files in snapshot'),
 	createdAt: z.string().describe('Snapshot creation timestamp'),
@@ -17,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'),
@@ -27,37 +33,76 @@ export const createSubcommand = createCommand({
 			command: getCommand('cloud sandbox snapshot create sbx_abc123 --tag latest'),
 			description: 'Create a tagged snapshot',
 		},
+		{
+			command: getCommand(
+				'cloud sandbox snapshot create sbx_abc123 --name "My Snapshot" --description "Initial setup"'
+			),
+			description: 'Create a named snapshot with description',
+		},
 	],
 	schema: {
 		args: z.object({
 			sandboxId: z.string().describe('Sandbox ID to snapshot'),
 		}),
 		options: z.object({
-			tag: z.string().optional().describe('Tag for the snapshot'),
+			name: z
+				.string()
+				.optional()
+				.describe('Display name for the snapshot (letters, numbers, underscores, dashes only)'),
+			description: z.string().optional().describe('Description of the snapshot'),
+			tag: z.string().optional().describe('Tag for the snapshot (defaults to "latest")'),
 		}),
 		response: SnapshotCreateResponseSchema,
 	},
 
 	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(
+				'Invalid snapshot name: must only contain letters, numbers, underscores, and dashes'
+			);
+		}
+
+		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`
+				);
+			}
+			if (!SNAPSHOT_TAG_REGEX.test(opts.tag)) {
+				logger.fatal(
+					'Invalid snapshot tag: must only contain letters, numbers, dashes, underscores, and dots, and cannot start with a period or dash'
+				);
+			}
+		}
+
+		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, {
 			sandboxId: args.sandboxId,
+			name: opts.name,
+			description: opts.description,
 			tag: opts.tag,
 			orgId,
 		});
 
 		if (!options.json) {
 			tui.success(`created snapshot ${tui.bold(snapshot.snapshotId)}`);
-			tui.info(`Size: ${tui.formatBytes(snapshot.sizeBytes)}, Files: ${snapshot.fileCount}`);
-			if (snapshot.tag) {
-				tui.info(`Tag: ${snapshot.tag}`);
+			tui.info(`Name: ${snapshot.name}`);
+			if (snapshot.description) {
+				tui.info(`Description: ${snapshot.description}`);
 			}
+			tui.info(`Size: ${tui.formatBytes(snapshot.sizeBytes)}, Files: ${snapshot.fileCount}`);
+			tui.info(`Tag: ${snapshot.tag ?? 'latest'}`);
 		}
 
 		return {
 			snapshotId: snapshot.snapshotId,
+			name: snapshot.name,
+			description: snapshot.description ?? undefined,
 			tag: snapshot.tag ?? undefined,
 			sizeBytes: snapshot.sizeBytes,
 			fileCount: snapshot.fileCount,

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,