@agentuity/cli 1.0.11 → 1.0.13

package/src/cmd/cloud/keyvalue/stats.ts

@@ -3,6 +3,15 @@ import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
+const KVStatsPaginatedSchema = z
+	.object({
+		total: z.number().describe('Total number of namespaces across all pages'),
+		limit: z.number().describe('Number of namespaces requested per page'),
+		offset: z.number().describe('Number of namespaces skipped'),
+		hasMore: z.boolean().describe('Whether there are more namespaces available'),
+	})
+	.passthrough();
+
 const KVStatsResponseSchema = z.union([
 	z.object({
 		namespace: z.string().describe('Namespace name'),
@@ -20,6 +29,7 @@ const KVStatsResponseSchema = z.union([
 			lastUsedAt: z.string().optional().describe('Last used timestamp'),
 		})
 	),
+	KVStatsPaginatedSchema,
 ]);
 
 export const statsSubcommand = createCommand({
@@ -41,13 +51,27 @@ export const statsSubcommand = createCommand({
 		args: z.object({
 			name: z.string().optional().describe('the keyvalue namespace'),
 		}),
+		options: z.object({
+			name: z.string().optional().describe('Filter namespaces by name'),
+			sort: z
+				.enum(['name', 'size', 'records', 'created', 'lastUsed'])
+				.default('name')
+				.describe('field to sort by'),
+			direction: z.enum(['asc', 'desc']).default('asc').describe('sort direction'),
+			limit: z.coerce.number().min(0).optional().describe('Maximum number of results to return'),
+			offset: z.coerce.number().min(0).optional().describe('Offset for pagination'),
+			projectId: z.string().optional().describe('Filter by project ID'),
+			agentId: z.string().optional().describe('Filter by agent ID'),
+			projectName: z.string().optional().describe('Filter by project name'),
+			agentName: z.string().optional().describe('Filter by agent name'),
+		}),
 		response: KVStatsResponseSchema,
 	},
 	webUrl: (ctx) =>
 		ctx.args.name ? `/services/kv/${encodeURIComponent(ctx.args.name)}` : '/services/kv',
 
 	async handler(ctx) {
-		const { args, options } = ctx;
+		const { args, options, opts } = ctx;
 		const kv = await createStorageAdapter(ctx);
 
 		if (args.name) {
@@ -77,15 +101,56 @@ export const statsSubcommand = createCommand({
 				lastUsedAt: stats.lastUsedAt ? String(stats.lastUsedAt) : undefined,
 			};
 		} else {
-			const allStats = await kv.getAllStats();
-			const entries = Object.entries(allStats);
+			const allStats = await kv.getAllStats({
+				...(opts?.name && { name: opts.name }),
+				...(opts?.sort && { sort: opts.sort }),
+				...(opts?.direction && { direction: opts.direction }),
+				...(opts?.limit !== undefined && { limit: opts.limit }),
+				...(opts?.offset !== undefined && { offset: opts.offset }),
+				...(opts?.projectId && { projectId: opts.projectId }),
+				...(opts?.agentId && { agentId: opts.agentId }),
+				...(opts?.projectName && { projectName: opts.projectName }),
+				...(opts?.agentName && { agentName: opts.agentName }),
+			});
+
+			// Handle both paginated and flat response formats.
+			// Strictly validate pagination shape to avoid misclassifying a flat response
+			// that happens to contain a namespace literally named "namespaces".
+			const isPaginated =
+				allStats != null &&
+				typeof allStats === 'object' &&
+				'namespaces' in allStats &&
+				'total' in allStats &&
+				typeof (allStats as Record<string, unknown>).total === 'number' &&
+				typeof (allStats as Record<string, unknown>).namespaces === 'object' &&
+				(allStats as Record<string, unknown>).namespaces != null &&
+				// A paginated namespaces value is a Record of namespace entries (each with count/sum),
+				// not itself a single namespace entry (which would have count/sum at the top level).
+				!('count' in ((allStats as Record<string, unknown>).namespaces as object));
+			const namespaceMap = isPaginated
+				? (
+						allStats as {
+							namespaces: Record<
+								string,
+								{ count: number; sum: number; createdAt?: string; lastUsedAt?: string }
+							>;
+						}
+					).namespaces
+				: (allStats as Record<
+						string,
+						{ count: number; sum: number; createdAt?: string; lastUsedAt?: string }
+					>);
+			const entries = Object.entries(namespaceMap);
 
 			if (!options.json) {
 				if (entries.length === 0) {
 					tui.info('No namespaces found');
 				} else {
+					const totalInfo = isPaginated
+						? ` (showing ${entries.length} of ${(allStats as { total: number }).total})`
+						: '';
 					tui.info(
-						`Found ${entries.length} ${tui.plural(entries.length, 'namespace', 'namespaces')}:`
+						`Found ${entries.length} ${tui.plural(entries.length, 'namespace', 'namespaces')}${totalInfo}:`
 					);
 					for (const [name, stats] of entries) {
 						const sizeDisplay =
@@ -99,15 +164,44 @@ export const statsSubcommand = createCommand({
 				}
 			}
 
-			// Convert timestamp fields to strings
+			// For JSON output with pagination, include metadata
+			if (isPaginated) {
+				const paginatedResult = allStats as {
+					namespaces: Record<
+						string,
+						{ count: number; sum: number; createdAt?: string; lastUsedAt?: string }
+					>;
+					total: number;
+					limit: number;
+					offset: number;
+					hasMore: boolean;
+				};
+				// Convert timestamps to strings in namespaces
+				const namespaces: Record<
+					string,
+					{ count: number; sum: number; createdAt?: string; lastUsedAt?: string }
+				> = {};
+				for (const [name, stats] of entries) {
+					namespaces[name] = {
+						count: stats.count,
+						sum: stats.sum,
+						createdAt: stats.createdAt ? String(stats.createdAt) : undefined,
+						lastUsedAt: stats.lastUsedAt ? String(stats.lastUsedAt) : undefined,
+					};
+				}
+				return {
+					namespaces,
+					total: paginatedResult.total,
+					limit: paginatedResult.limit,
+					offset: paginatedResult.offset,
+					hasMore: paginatedResult.hasMore,
+				};
+			}
+
+			// Non-paginated: return flat map
 			const result: Record<
 				string,
-				{
-					count: number;
-					sum: number;
-					createdAt?: string;
-					lastUsedAt?: string;
-				}
+				{ count: number; sum: number; createdAt?: string; lastUsedAt?: string }
 			> = {};
 			for (const [name, stats] of entries) {
 				result[name] = {

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

@@ -32,16 +32,19 @@ export const listSubcommand = createCommand({
 		args: z.object({}),
 		options: z.object({
 			orgId: z.string().optional().describe('filter by organization id'),
-			limit: z.coerce.number().optional().describe('Maximum number of queues to return'),
-			offset: z.coerce.number().optional().describe('Offset for pagination'),
-			sort: z
-				.enum(['name', 'created', 'updated'])
-				.optional()
-				.describe('field to sort by (default: created)'),
-			direction: z
-				.enum(['asc', 'desc'])
+			limit: z.coerce.number().min(0).optional().describe('Maximum number of queues to return'),
+			offset: z.coerce.number().min(0).optional().describe('Offset for pagination'),
+			name: z.string().optional().describe('Filter by queue name'),
+			queueType: z.enum(['worker', 'pubsub']).optional().describe('Filter by queue type'),
+			status: z
+				.enum(['active', 'paused'])
 				.optional()
-				.describe('sort direction (default: desc)'),
+				.describe('Filter by queue status (active or paused)'),
+			sort: z
+				.enum(['name', 'created', 'updated', 'message_count', 'dlq_count'])
+				.default('created')
+				.describe('field to sort by'),
+			direction: z.enum(['asc', 'desc']).default('desc').describe('sort direction'),
 		}),
 		response: QueueListResponseSchema,
 	},
@@ -58,6 +61,9 @@ export const listSubcommand = createCommand({
 				offset: opts.offset,
 				sort: opts.sort,
 				direction: opts.direction,
+				name: opts.name,
+				queue_type: opts.queueType,
+				status: opts.status,
 			},
 			queueOptions
 		);

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

@@ -66,6 +66,8 @@ export const listSubcommand = createCommand({
 	],
 	schema: {
 		options: z.object({
+			name: z.string().optional().describe('Filter by sandbox name'),
+			mode: z.enum(['oneshot', 'interactive']).optional().describe('Filter by sandbox mode'),
 			status: z
 				.enum(['creating', 'idle', 'running', 'terminated', 'failed'])
 				.optional()
@@ -73,16 +75,13 @@ export const listSubcommand = createCommand({
 			projectId: z.string().optional().describe('Filter by project ID'),
 			orgId: z.string().optional().describe('Filter by organization ID'),
 			all: z.boolean().optional().describe('List all sandboxes regardless of project context'),
-			limit: z.number().optional().describe('Maximum number of results (default: 50, max: 100)'),
-			offset: z.number().optional().describe('Pagination offset'),
+			limit: z.number().min(0).default(50).describe('Maximum number of results (max: 100)'),
+			offset: z.number().min(0).optional().describe('Pagination offset'),
 			sort: z
-				.enum(['name', 'created', 'updated', 'status'])
-				.optional()
-				.describe('field to sort by (default: created)'),
-			direction: z
-				.enum(['asc', 'desc'])
-				.optional()
-				.describe('sort direction (default: desc)'),
+				.enum(['name', 'created', 'updated', 'status', 'mode', 'execution_count'])
+				.default('created')
+				.describe('field to sort by'),
+			direction: z.enum(['asc', 'desc']).default('desc').describe('sort direction'),
 		}),
 		response: SandboxListResponseSchema,
 	},
@@ -97,6 +96,8 @@ export const listSubcommand = createCommand({
 		const projectId = opts.all || opts.orgId ? undefined : opts.projectId || project?.projectId;
 
 		const result = await cliSandboxList(apiClient, {
+			name: opts.name,
+			mode: opts.mode,
 			projectId,
 			orgId: opts.orgId,
 			status: opts.status,

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

@@ -38,10 +38,7 @@ export const listSubcommand = createCommand({
 				.enum(['name', 'created'])
 				.optional()
 				.describe('field to sort by (default: created)'),
-			direction: z
-				.enum(['asc', 'desc'])
-				.optional()
-				.describe('sort direction (default: desc)'),
+			direction: z.enum(['asc', 'desc']).optional().describe('sort direction (default: desc)'),
 		}),
 		response: RuntimeListResponseSchema,
 	},

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

@@ -48,13 +48,10 @@ export const listSubcommand = createCommand({
 			offset: z.number().optional().describe('Offset for pagination'),
 			orgId: z.string().optional().describe('filter by organization id'),
 			sort: z
-				.enum(['name', 'created', 'size'])
+				.enum(['name', 'created', 'size', 'files'])
 				.optional()
 				.describe('field to sort by (default: created)'),
-			direction: z
-				.enum(['asc', 'desc'])
-				.optional()
-				.describe('sort direction (default: desc)'),
+			direction: z.enum(['asc', 'desc']).optional().describe('sort direction (default: desc)'),
 		}),
 		response: SnapshotListResponseSchema,
 	},

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

@@ -95,10 +95,7 @@ export const listSubcommand = createSubcommand({
 				.enum(['created', 'updated', 'duration', 'startTime'])
 				.optional()
 				.describe('field to sort by (default: created)'),
-			direction: z
-				.enum(['asc', 'desc'])
-				.optional()
-				.describe('sort direction (default: desc)'),
+			direction: z.enum(['asc', 'desc']).optional().describe('sort direction (default: desc)'),
 		}),
 		response: SessionListResponseSchema,
 	},
@@ -117,22 +114,22 @@ export const listSubcommand = createSubcommand({
 		const projectId = opts.all || opts.orgId ? undefined : opts.projectId || project?.projectId;
 
 		try {
-		const sessions = await sessionList(catalystClient, {
-			count: opts.count,
-			orgId: opts?.orgId,
-			projectId,
-			deploymentId: opts.deploymentId,
-			trigger: opts.trigger,
-			env: opts.env,
-			devmode: opts.devmode,
-			success: opts.success,
-			threadId: opts.threadId,
-			agentIdentifier: opts.agentIdentifier,
-			startAfter: opts.startAfter,
-			startBefore: opts.startBefore,
-			sort: opts.sort,
-			direction: opts.direction,
-		});
+			const sessions = await sessionList(catalystClient, {
+				count: opts.count,
+				orgId: opts?.orgId,
+				projectId,
+				deploymentId: opts.deploymentId,
+				trigger: opts.trigger,
+				env: opts.env,
+				devmode: opts.devmode,
+				success: opts.success,
+				threadId: opts.threadId,
+				agentIdentifier: opts.agentIdentifier,
+				startAfter: opts.startAfter,
+				startBefore: opts.startBefore,
+				sort: opts.sort,
+				direction: opts.direction,
+			});
 
 			const result = sessions.map((s) => ({
 				id: s.id,

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

@@ -70,6 +70,7 @@ export const listSubcommand = createSubcommand({
 		}),
 		options: z.object({
 			orgId: z.string().optional().describe('filter by organization id'),
+			name: z.string().optional().describe('Filter by bucket name'),
 			showCredentials: z
 				.boolean()
 				.optional()
@@ -78,13 +79,12 @@ export const listSubcommand = createSubcommand({
 				),
 			nameOnly: z.boolean().optional().describe('Print the name only'),
 			sort: z
-				.enum(['name', 'created'])
-				.optional()
-				.describe('field to sort by (default: created)'),
-			direction: z
-				.enum(['asc', 'desc'])
-				.optional()
-				.describe('sort direction (default: desc)'),
+				.enum(['name', 'created', 'region'])
+				.default('created')
+				.describe('field to sort by'),
+			direction: z.enum(['asc', 'desc']).default('desc').describe('sort direction'),
+			limit: z.coerce.number().min(0).optional().describe('Maximum number of results to return'),
+			offset: z.coerce.number().min(0).optional().describe('Offset for pagination'),
 		}),
 		response: StorageListResponseSchema,
 	},
@@ -106,8 +106,15 @@ export const listSubcommand = createSubcommand({
 				return listOrgResources(catalystClient, {
 					type: 's3',
 					orgId: opts?.orgId,
-					sort: opts?.sort,
-					direction: opts?.direction,
+					...(args.name
+						? { name: args.name }
+						: {
+								name: opts?.name,
+								sort: opts?.sort,
+								direction: opts?.direction,
+								limit: opts?.limit,
+								offset: opts?.offset,
+							}),
 				});
 			},
 		});

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

@@ -58,9 +58,10 @@ export const listSubcommand = createCommand({
 	],
 	schema: {
 		options: z.object({
-			size: z.number().optional().describe('maximum number of streams to return (default: 100)'),
-			offset: z.number().optional().describe('number of streams to skip for pagination'),
+			size: z.number().min(1).default(100).describe('maximum number of streams to return'),
+			offset: z.number().min(0).optional().describe('number of streams to skip for pagination'),
 			namespace: z.string().optional().describe('filter by stream namespace'),
+			name: z.string().optional().describe('Filter by stream name'),
 			metadata: z
 				.string()
 				.optional()
@@ -68,13 +69,10 @@ export const listSubcommand = createCommand({
 			projectId: z.string().optional().describe('filter by project ID'),
 			orgId: z.string().optional().describe('filter by organization ID'),
 			sort: z
-				.enum(['name', 'created', 'updated', 'size'])
-				.optional()
-				.describe('field to sort by (default: created)'),
-			direction: z
-				.enum(['asc', 'desc'])
-				.optional()
-				.describe('sort direction (default: desc)'),
+				.enum(['name', 'created', 'updated', 'size', 'count', 'lastUsed'])
+				.default('created')
+				.describe('field to sort by'),
+			direction: z.enum(['asc', 'desc']).default('desc').describe('sort direction'),
 		}),
 		response: ListStreamsResponseSchema,
 	},
@@ -128,16 +126,17 @@ export const listSubcommand = createCommand({
 		}
 
 		try {
-		const result = await streamList(apiClient, {
-			limit: opts.size,
-			offset: opts.offset,
-			namespace: opts.namespace,
-			metadata: metadataFilter,
-			projectId,
-			orgId: opts.orgId,
-			sort: opts.sort,
-			direction: opts.direction,
-		});
+			const result = await streamList(apiClient, {
+				limit: opts.size,
+				offset: opts.offset,
+				namespace: opts.namespace,
+				name: opts.name,
+				metadata: metadataFilter,
+				projectId,
+				orgId: opts.orgId,
+				sort: opts.sort,
+				direction: opts.direction,
+			});
 
 			if (options.json) {
 				console.log(JSON.stringify(result, null, 2));

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

@@ -67,10 +67,7 @@ export const listSubcommand = createSubcommand({
 				.enum(['created', 'updated'])
 				.optional()
 				.describe('field to sort by (default: created)'),
-			direction: z
-				.enum(['asc', 'desc'])
-				.optional()
-				.describe('sort direction (default: desc)'),
+			direction: z.enum(['asc', 'desc']).optional().describe('sort direction (default: desc)'),
 		}),
 		response: ThreadListResponseSchema,
 	},
@@ -86,13 +83,13 @@ export const listSubcommand = createSubcommand({
 		const orgId = opts.orgId;
 
 		try {
-		const threads = await threadList(catalystClient, {
-			count: opts.count,
-			orgId,
-			projectId,
-			sort: opts.sort,
-			direction: opts.direction,
-		});
+			const threads = await threadList(catalystClient, {
+				count: opts.count,
+				orgId,
+				projectId,
+				sort: opts.sort,
+				direction: opts.direction,
+			});
 
 			const result = threads.map((t: Thread) => ({
 				id: t.id,

package/src/cmd/cloud/vector/stats.ts

@@ -59,13 +59,23 @@ export const statsSubcommand = createCommand({
 		args: z.object({
 			name: z.string().optional().describe('the vector namespace (optional)'),
 		}),
+		options: z.object({
+			name: z.string().optional().describe('Filter namespaces by name'),
+			sort: z
+				.enum(['name', 'size', 'records', 'created', 'lastUsed'])
+				.default('name')
+				.describe('field to sort by'),
+			direction: z.enum(['asc', 'desc']).default('asc').describe('sort direction'),
+			limit: z.coerce.number().min(0).optional().describe('Maximum number of results to return'),
+			offset: z.coerce.number().min(0).optional().describe('Offset for pagination'),
+		}),
 		response: VectorStatsResponseSchema,
 	},
 	webUrl: (ctx) =>
 		ctx.args.name ? `/services/vector/${encodeURIComponent(ctx.args.name)}` : '/services/vector',
 
 	async handler(ctx) {
-		const { args, options } = ctx;
+		const { args, options, opts } = ctx;
 		const storage = await createStorageAdapter(ctx);
 
 		if (args.name) {
@@ -125,15 +135,40 @@ export const statsSubcommand = createCommand({
 				...stats,
 			};
 		} else {
-			const allStats = await storage.getAllStats();
-			const entries = Object.entries(allStats);
+			const allStats = await storage.getAllStats({
+				...(opts?.name && { name: opts.name }),
+				...(opts?.sort && { sort: opts.sort }),
+				...(opts?.direction && { direction: opts.direction }),
+				...(opts?.limit !== undefined && { limit: opts.limit }),
+				...(opts?.offset !== undefined && { offset: opts.offset }),
+			});
+
+			// Handle both paginated and flat response formats
+			const isPaginated = allStats && typeof allStats === 'object' && 'namespaces' in allStats;
+			const namespaceMap = isPaginated
+				? (
+						allStats as {
+							namespaces: Record<
+								string,
+								{ sum: number; count: number; createdAt?: number; lastUsed?: number }
+							>;
+						}
+					).namespaces
+				: (allStats as Record<
+						string,
+						{ sum: number; count: number; createdAt?: number; lastUsed?: number }
+					>);
+			const entries = Object.entries(namespaceMap);
 
 			if (!options.json) {
 				if (entries.length === 0) {
 					tui.info('No vector namespaces found');
 				} else {
+					const totalInfo = isPaginated
+						? ` (showing ${entries.length} of ${(allStats as { total: number }).total})`
+						: '';
 					tui.info(
-						`Found ${entries.length} ${tui.plural(entries.length, 'namespace', 'namespaces')}:`
+						`Found ${entries.length} ${tui.plural(entries.length, 'namespace', 'namespaces')}${totalInfo}:`
 					);
 
 					const tableData = entries.map(([name, stats]) => {

package/src/cmd/dev/file-watcher.ts

@@ -84,6 +84,40 @@ export function createFileWatcher(options: FileWatcherOptions): FileWatcherManag
 		'src/generated', // Generated files shouldn't trigger rebuilds
 	];
 
+	// File extensions to ignore - non-code files that shouldn't trigger reload
+	const ignoreExtensions = new Set([
+		'.md',
+		'.mdx',
+		'.txt',
+		'.log',
+		'.lock',
+		'.yaml',
+		'.yml',
+		'.toml',
+		'.csv',
+		'.svg',
+		'.png',
+		'.jpg',
+		'.jpeg',
+		'.gif',
+		'.webp',
+		'.ico',
+		'.woff',
+		'.woff2',
+		'.ttf',
+		'.eot',
+		'.mp4',
+		'.mp3',
+		'.wav',
+		'.ogg',
+		'.webm',
+		'.pdf',
+		'.zip',
+		'.tar',
+		'.gz',
+		'.map',
+	]);
+
 	/**
 	 * Check if a path should be ignored
 	 */
@@ -134,6 +168,16 @@ export function createFileWatcher(options: FileWatcherOptions): FileWatcherManag
 			return true;
 		}
 
+		// Ignore files with non-code extensions
+		const extIndex = changedFile.lastIndexOf('.');
+		if (extIndex !== -1) {
+			const ext = changedFile.slice(extIndex).toLowerCase();
+			if (ignoreExtensions.has(ext)) {
+				logger.trace('File change ignored (%s): %s', ext, changedFile);
+				return true;
+			}
+		}
+
 		// Ignore hidden files (except .env)
 		if (changedFile.startsWith('.') && !changedFile.startsWith('.env')) {
 			logger.trace('File change ignored (hidden file): %s', changedFile);

package/src/cmd/upgrade/index.ts

@@ -4,7 +4,6 @@ import { getCommand } from '../../command-prefix';
 import { z } from 'zod';
 import { ErrorCode, createError, exitWithError } from '../../errors';
 import * as tui from '../../tui';
-import { $ } from 'bun';
 import { tmpdir } from 'node:os';
 import { getInstallationType, type InstallationType } from '../../utils/installation-type';
 
@@ -84,14 +83,17 @@ async function performBunUpgrade(
 	const { installWithRetry } = await import('./npm-availability');
 
 	try {
+		const { spawnWithTimeout } = await import('./npm-availability');
+
 		await installWithRetry(
 			async () => {
 				// Use bun to install the specific version globally
 				// Run from tmpdir to avoid interference from any local package.json/node_modules
-				const result = await $`bun add -g @agentuity/cli@${npmVersion}`
-					.cwd(tmpdir())
-					.quiet()
-					.nothrow();
+				// spawnWithTimeout kills the process if it exceeds 30s (INSTALL_TIMEOUT_MS)
+				const result = await spawnWithTimeout(
+					['bun', 'add', '-g', `@agentuity/cli@${npmVersion}`],
+					{ cwd: tmpdir(), timeout: 30_000 }
+				);
 				return { exitCode: result.exitCode, stderr: result.stderr };
 			},
 			{ onRetry }
@@ -107,8 +109,10 @@ async function performBunUpgrade(
  * Verify the upgrade was successful by checking the installed version
  */
 async function verifyUpgrade(expectedVersion: string): Promise<void> {
-	// Run agentuity version to check the installed version
-	const result = await $`agentuity version`.quiet().nothrow();
+	const { spawnWithTimeout } = await import('./npm-availability');
+
+	// Run agentuity version to check the installed version (5s timeout — local command, sub-second normally)
+	const result = await spawnWithTimeout(['agentuity', 'version'], { timeout: 5_000 });
 
 	if (result.exitCode !== 0) {
 		throw new Error('Failed to verify upgrade - could not run agentuity version');
@@ -220,7 +224,9 @@ export const command = createCommand({
 			if (!isAvailable) {
 				tui.warning('The new version is not yet available on npm.');
 				tui.info('This can happen right after a release. Please try again in a few minutes.');
-				tui.info(`You can also run: ${tui.muted('bun add -g @agentuity/cli@latest')}`);
+				tui.newline();
+				tui.info('You can also upgrade manually:');
+				console.log(`  ${tui.muted('curl -fsSL https://agentuity.sh | sh')}`);
 				return {
 					upgraded: false,
 					from: currentVersion,
@@ -301,6 +307,12 @@ export const command = createCommand({
 				installationType,
 			};
 
+			tui.newline();
+			tui.info('If the upgrade continues to fail, you can reinstall manually:');
+			tui.newline();
+			console.log(`  ${tui.muted('curl -fsSL https://agentuity.sh | sh')}`);
+			tui.newline();
+
 			exitWithError(
 				createError(ErrorCode.INTERNAL_ERROR, 'Upgrade failed', errorDetails),
 				logger,